update from main archive 961114
authordrepper <drepper>
Fri, 15 Nov 1996 03:53:05 +0000 (03:53 +0000)
committerdrepper <drepper>
Fri, 15 Nov 1996 03:53:05 +0000 (03:53 +0000)
manual/examples/rprintf.c
manual/stdio.texi

index eff1d8e..723b3a3 100644 (file)
@@ -9,7 +9,7 @@ typedef struct
   } Widget;
 /*@end group*/
 
   } Widget;
 /*@end group*/
 
-int 
+int
 print_widget (FILE *stream, const struct printf_info *info, va_list *app)
 {
   Widget *w;
 print_widget (FILE *stream, const struct printf_info *info, va_list *app)
 {
   Widget *w;
@@ -34,6 +34,18 @@ print_widget (FILE *stream, const struct printf_info *info, va_list *app)
 
 
 int
 
 
 int
+print_widget_arginfo (const struct printf_info *info, size_t n,
+                      int *argtypes)
+{
+  /* We always take exactly one argument and this is a pointer to the
+     structure..  */
+  if (n > 0)
+    argtypes[0] = PA_POINTER;
+  return 1;
+}
+
+
+int
 main (void)
 {
   /* Make a widget to print. */
 main (void)
 {
   /* Make a widget to print. */
@@ -41,7 +53,7 @@ main (void)
   mywidget.name = "mywidget";
 
   /* Register the print function for widgets. */
   mywidget.name = "mywidget";
 
   /* Register the print function for widgets. */
-  register_printf_function ('W', print_widget, NULL); /* No arginfo.  */
+  register_printf_function ('W', print_widget, print_widget_arginfo);
 
   /* Now print the widget. */
   printf ("|%W|\n", &mywidget);
 
   /* Now print the widget. */
   printf ("|%W|\n", &mywidget);
index c666f5e..e6e5614 100644 (file)
@@ -1943,9 +1943,19 @@ The @var{arginfo-function} is the function called by
 template string.  @xref{Parsing a Template String}, for information
 about this.
 
 template string.  @xref{Parsing a Template String}, for information
 about this.
 
-Normally, you install both functions for a conversion at the same time,
-but if you are never going to call @code{parse_printf_format}, you do
-not need to define an arginfo function.
+@c The following is not true anymore.  The `parse_printf_format' function
+@c is now also called from `vfprintf' via `parse_one_spec'.
+@c --drepper@gnu, 1996/11/14
+@c
+@c Normally, you install both functions for a conversion at the same time,
+@c but if you are never going to call @code{parse_printf_format}, you do
+@c not need to define an arginfo function.
+
+@strong{Attention:} In the GNU C library version before 2.0 the
+@var{arginfo-function} function did not need to be installed unless
+the user uses the @code{parse_printf_format} function.  This changed.
+Now a call to any of the @code{printf} functions will call this
+function when this format specifier appears in the format string.
 
 The return value is @code{0} on success, and @code{-1} on failure
 (which occurs if @var{spec} is out of range).
 
 The return value is @code{0} on success, and @code{-1} on failure
 (which occurs if @var{spec} is out of range).
@@ -1995,7 +2005,7 @@ actual value retrieved from the argument list.  But the structure passed
 to the arginfo function contains a value of @code{INT_MIN}, since the
 actual value is not known.
 
 to the arginfo function contains a value of @code{INT_MIN}, since the
 actual value is not known.
 
-@item char spec
+@item wchar_t spec
 This is the conversion specifier character specified.  It's stored in
 the structure so that you can register the same handler function for
 multiple characters, but still have a way to tell them apart when the
 This is the conversion specifier character specified.  It's stored in
 the structure so that you can register the same handler function for
 multiple characters, but still have a way to tell them apart when the
@@ -2028,7 +2038,13 @@ This is a boolean that is true if the @samp{+} flag was specified.
 @item unsigned int group
 This is a boolean that is true if the @samp{'} flag was specified.
 
 @item unsigned int group
 This is a boolean that is true if the @samp{'} flag was specified.
 
-@item char pad
+@item unsigned int extra
+This flag has a special meaning depending on the context.  It could
+be used freely by the user-defined handlers but when called from
+the @code{printf} function this variable always contains the value
+@code{0}.
+
+@item wchar_t pad
 This is the character to use for padding the output to the minimum field
 width.  The value is @code{'0'} if the @samp{0} flag was specified, and
 @code{' '} otherwise.
 This is the character to use for padding the output to the minimum field
 width.  The value is @code{'0'} if the @samp{0} flag was specified, and
 @code{' '} otherwise.
@@ -2042,32 +2058,42 @@ width.  The value is @code{'0'} if the @samp{0} flag was specified, and
 Now let's look at how to define the handler and arginfo functions
 which are passed as arguments to @code{register_printf_function}.
 
 Now let's look at how to define the handler and arginfo functions
 which are passed as arguments to @code{register_printf_function}.
 
+@strong{Compatibility Note:} The interface change in the GNU libc
+version 2.0.  Previously the third argument was of type
+@code{va_list *}.
+
 You should define your handler functions with a prototype like:
 
 @smallexample
 int @var{function} (FILE *stream, const struct printf_info *info,
 You should define your handler functions with a prototype like:
 
 @smallexample
 int @var{function} (FILE *stream, const struct printf_info *info,
-                    va_list *ap_pointer)
+                    const void *const *args)
 @end smallexample
 
 @end smallexample
 
-The @code{stream} argument passed to the handler function is the stream to
+The @var{stream} argument passed to the handler function is the stream to
 which it should write output.
 
 which it should write output.
 
-The @code{info} argument is a pointer to a structure that contains
+The @var{info} argument is a pointer to a structure that contains
 information about the various options that were included with the
 conversion in the template string.  You should not modify this structure
 inside your handler function.  @xref{Conversion Specifier Options}, for
 a description of this data structure.
 
 information about the various options that were included with the
 conversion in the template string.  You should not modify this structure
 inside your handler function.  @xref{Conversion Specifier Options}, for
 a description of this data structure.
 
-The @code{ap_pointer} argument is used to pass the tail of the variable
-argument list containing the values to be printed to your handler.
-Unlike most other functions that can be passed an explicit variable
-argument list, this is a @emph{pointer} to a @code{va_list}, rather than
-the @code{va_list} itself.  Thus, you should fetch arguments by
-means of @code{va_arg (*ap_pointer, @var{type})}.
-
-(Passing a pointer here allows the function that calls your handler
-function to update its own @code{va_list} variable to account for the
-arguments that your handler processes.  @xref{Variadic Functions}.)
+@c The following changes some time back.  --drepper@gnu, 1996/11/14
+@c
+@c The @code{ap_pointer} argument is used to pass the tail of the variable
+@c argument list containing the values to be printed to your handler.
+@c Unlike most other functions that can be passed an explicit variable
+@c argument list, this is a @emph{pointer} to a @code{va_list}, rather than
+@c the @code{va_list} itself.  Thus, you should fetch arguments by
+@c means of @code{va_arg (*ap_pointer, @var{type})}.
+@c
+@c (Passing a pointer here allows the function that calls your handler
+@c function to update its own @code{va_list} variable to account for the
+@c arguments that your handler processes.  @xref{Variadic Functions}.)
+
+The @var{args} is a vector of pointers to the arguments data.
+The number of arguments were determined by calling the argument
+information function provided by the user.
 
 Your handler function should return a value just like @code{printf}
 does: it should return the number of characters it has written, or a
 
 Your handler function should return a value just like @code{printf}
 does: it should return the number of characters it has written, or a
@@ -2080,11 +2106,11 @@ This is the data type that a handler function should have.
 @end deftp
 
 If you are going to use @w{@code{parse_printf_format}} in your
 @end deftp
 
 If you are going to use @w{@code{parse_printf_format}} in your
-application, you should also define a function to pass as the
+application, you must also define a function to pass as the
 @var{arginfo-function} argument for each new conversion you install with
 @code{register_printf_function}.
 
 @var{arginfo-function} argument for each new conversion you install with
 @code{register_printf_function}.
 
-You should define these functions with a prototype like:
+You have to define these functions with a prototype like:
 
 @smallexample
 int @var{function} (const struct printf_info *info,
 
 @smallexample
 int @var{function} (const struct printf_info *info,