Fixed some formatting and indexing problems.
[kopensolaris-gnu/glibc.git] / manual / =stdarg.texi
index 1ee21af..b903e44 100644 (file)
@@ -1,6 +1,5 @@
 @node Variable Argument Facilities
 @chapter Variable Argument Facilities
-@pindex <stdarg.h>
 @cindex variadic argument functions
 @cindex variadic functions
 @cindex variable number of arguments
@@ -11,9 +10,9 @@ functions that take a variable number or type of arguments.  (Such
 functions are also referred to as @dfn{variadic argument functions}, or
 simply @dfn{variadic functions}.)  However, the kernel language provides
 no mechanism for actually accessing non-required arguments; instead,
-this mechanism is defined as a set of macros in the C library as a
-standard language extension.  You must include the header file
-@file{<stdarg.h>} to make use of these macros.
+you use the variable arguments macros defined in
+@file{stdarg.h}.
+@pindex stdarg.h
 
 @menu
 * Why Variable Arguments are Used::    
@@ -30,7 +29,7 @@ standard language extension.  You must include the header file
 Most C functions take a fixed number of arguments.  When you declare or
 define a function, you also supply a specific data type for each 
 argument.  Calls to the function with the wrong number or type of 
-arguments don't work.
+arguments cause compile-time error messages.
 
 On the other hand, sometimes a function performs an operation that makes
 sense no matter how many arguments it is called with.  
@@ -56,9 +55,9 @@ well as number) under the control of a format template string.
 @node How Variable Arguments are Used
 @section How Variable Arguments are Used
 
-This section describes how functions that take variable arguments are
-defined and called, and how the values of the non-required arguments are
-accessed.
+This section describes how you can define and call functions that take
+variable arguments, and how to access the values of the non-required
+arguments.
 
 @menu
 * Syntax for Variable Arguments::      How to make a prototype for a function
@@ -74,16 +73,14 @@ accessed.
 @node Syntax for Variable Arguments
 @subsection Syntax for Variable Arguments
 
-The syntax in the language kernel requires that a function that accepts
-a variable number of arguments have at least one required argument with
-a known type.  In the function definition or prototype declaration, the
-fact that a function can accept additional arguments of unspecified type
-is indicated with a trailing argument list of @samp{@dots{}}.  For
-example,
+A function that accepts a variable number of arguments must have at
+least one required argument with a specified type.  In the function
+definition or prototype declaration, you indicate the fact that a
+function can accept additional arguments of unspecified type by putting
+@samp{@dots{}} at the end of the arguments.  For example,
 
 @example
 int func (const char *a, int b, @dots{})
-@dots{}
 @end example
 
 @noindent
@@ -92,11 +89,12 @@ begins a definition of a function @code{func} which returns an
 @code{const char *} and an @code{int}.@refill
 
 An obscure restriction placed by the ANSI C standard is that the last
-required argument must not be declared with a @code{register} storage
-class in the actual function definition.  Furthermore, this argument
-must not be of a function or array type, or of a type that is not
-compatible with the type that results after application of the default
-argument promotions.
+required argument must not be declared @code{register} in the function
+definition.  Furthermore, this argument must not be of a function or
+array type, or of a type that is not compatible with the type that
+results after application of the default argument promotions --- for
+example, a @code{char} or @code{short int} (whether signed or not) or
+a @code{float}.
 
 @strong{Compatibility Note:} Many older C dialects provide a similar,
 but incompatible, mechanism for defining variadic arguments functions.
@@ -106,20 +104,20 @@ In particular, the @samp{@dots{}} syntax is a new feature of ANSI C.
 @node Receiving the Argument Values
 @subsection Receiving the Argument Values
 
-Inside the definition of a variadic arguments function, the optional
-arguments can be accessed using a set of macros.  The process consists
-of three steps:
+Inside the definition of a variadic arguments function, you can access
+the optional arguments using a set of macros.  The process consists of
+three steps:
 
 @enumerate
 @item
-A variable of type @code{va_list} is initialized using @code{va_start}.
+You initialize a variable of type @code{va_list} using @code{va_start}.
 
 @item
-The optional arguments are accessed by successive calls to @code{va_arg}.
+You access the optional arguments by successive calls to @code{va_arg}.
 
 @item
-A call to @code{va_end} performs any internal cleanup operations that are
-necessary.
+You call @code{va_end} to indicate that you are finished accessing the
+arguments.
 @end enumerate
 
 Steps 1 and 3 must be performed in the function that is defined to
@@ -134,7 +132,7 @@ within a single function invocation.  And, if the function doesn't want
 to look at its optional arguments at all, it doesn't have to do any of
 these steps.  It is also perfectly all right for a function to access
 fewer arguments than were supplied in the call, but you will get garbage
-values if you try to access more arguments than were actually supplied.
+values if you try to access too many arguments.
 
 
 @node How Many Arguments
@@ -144,13 +142,12 @@ There is no general way for a function to determine the number and type
 of the actual values that were passed as optional arguments.  Typically,
 the value of one of the required arguments is used to decide when to
 stop fetching more optional arguments.  It is up to you to define an
-appropriate protocol for each function, and write all callers
-appropriately.
+appropriate calling convention for each function, and write all calls
+accordingly.
 
-If all of the optional arguments are expected to be of the same type,
-making one of the required arguments be an explicit argument count is
-the most obvious technique for specifying how many optional arguments
-are supplied.
+One calling convention is to make one of the required arguments be an
+explicit argument count.  This works if all of the optional arguments
+are of the same type.
 
 A required argument can be used as a pattern to specify both the number
 and types of the optional arguments.  The format template string
@@ -165,8 +162,8 @@ retrieved, and otherwise a default value is used.
 Another technique that is sometimes used is to pass an ``end marker''
 value as the last optional argument.  For example, for a function that
 manipulates an arbitrary number of pointer arguments, a null pointer
-might be used to indicate the end of the argument list, provided that
-a null pointer isn't otherwise meaningful to the function.
+might indicate the end of the argument list, provided that a null
+pointer isn't otherwise meaningful to the function.
 
 
 @node Calling Variadic Functions
@@ -186,12 +183,12 @@ to call it incorrectly and your program won't work.
 Since the prototype doesn't specify types for optional arguments, in a
 call to a variadic function the @dfn{default argument promotions} are
 performed on the optional argument values.  This means the objects of
-type @code{char} or @code{short int}, or @code{int} bit fields, are
-promoted to either @code{int} or @code{unsigned int}, as appropriate;
-and that objects of type @code{float} are promoted to type
-@code{double}.  So, if the caller passes a @code{char} as an optional
-argument, it is promoted to a @code{int}, and the function should get it
-with @code{va_arg (@var{ap}, int)}.
+type @code{char} or @code{short int} are promoted to either @code{int}
+or @code{unsigned int}, as appropriate; and that objects of type
+@code{float} are promoted to type @code{double}.  So, if the caller
+passes a @code{char} as an optional argument, it is promoted to a
+@code{int}, and the function should get it with @code{va_arg (@var{ap},
+int)}.
 
 Promotions of the required arguments are determined by the function
 prototype in the usual way (as if by assignment to the types of the
@@ -203,7 +200,8 @@ corresponding formal parameters).
 @section Variable Arguments Interface
 
 Here are descriptions of the macros used to retrieve variable arguments.
-These macros are defined in the header file @file{<stdarg.h>}.
+These macros are defined in the header file @file{stdarg.h}.
+@pindex stdarg.h
 
 @comment stdarg.h
 @comment ANSI
@@ -227,19 +225,24 @@ the last required argument parameter to the function.  Initially, @var{ap}
 The @code{va_arg} macro returns the value of the next optional argument,
 and changes the internal state of @var{ap} to move past this argument.
 The type of the value returned by @code{va_arg} is the @var{type}
-specified in the call.  You must be careful that this @var{type}
-is the same as the type of the actual argument value after the default
-argument promotions are performed; if they aren't compatible, bad
-things will happen.
+specified in the call.  
+
+The @var{type} must match the type of the actual argument, and must not
+be @code{char} or @code{short int} or @code{float}.  (Remember that the
+default argument promotions apply to optional arguments.)
 @end deftypefn
 
 @comment stdarg.h
 @comment ANSI
 @deftypefn {Macro} void va_end (va_list @var{ap})
 This ends the use of @var{ap}.  After a @code{va_end} call, further
-@code{va_arg} calls with the same @var{ap} will not work.  You must invoke
+@code{va_arg} calls with the same @var{ap} will not work.  You should invoke
 @code{va_end} before returning from the function in which @code{va_start}
-was invoked with the same @var{ap} argument.@refill
+was invoked with the same @var{ap} argument.
+
+In the GNU C library, @code{va_end} does nothing, and you need not ever
+use it except for reasons of portability.
+@refill
 @end deftypefn
 
 
@@ -266,18 +269,19 @@ add_em_up (int count, @dots{})
   va_start (ap, count);           /* @r{Initialize the argument list.} */
 
   sum = 0;
-  for (i=0; i<count; i++)
+  for (i = 0; i < count; i++)
     sum = sum + va_arg (ap, int); /* @r{Get the next argument value.} */
 
   va_end (ap);                    /* @r{Clean up.} */
   return sum;
 @}
 
-@dots{}
-
+void main (void)
+@{
   /* @r{This call prints 16.} */
   printf ("%d\n", add_em_up (3, 5, 5, 6));
 
   /* @r{This call prints 55.} */
   printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
+@}
 @end example