(i[34]86sol2): New abbrev for i[34]86-unknown-solaris2.
[kopensolaris-gnu/glibc.git] / manual / =stdarg.texi
index 163a64c..384c992 100644 (file)
@@ -1,6 +1,5 @@
-@node Variable Argument Facilities
+@node Variable Argument Facilities, Memory Allocation, Common Definitions, Top
 @chapter Variable Argument Facilities
-@pindex <stdarg.h>
 @cindex variadic argument functions
 @cindex variadic functions
 @cindex variable number of arguments
@@ -8,32 +7,32 @@
 
 ANSI C defines a syntax as part of the kernel language for specifying
 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.
+functions are also referred to as @dfn{variadic functions}.)  However,
+the kernel language provides no mechanism for actually accessing
+non-required arguments; instead, you use the variable arguments macros
+defined in @file{stdarg.h}.
+@pindex stdarg.h
 
 @menu
-* Why Variable Arguments are Used::    
-* How Variable Arguments are Used::    An overview of the facilities for
-                                        receiving variable arguments.
-* Variable Arguments Interface::       Detailed specification of the
+* Why Variable Arguments are Used::     Using variable arguments can
+                                         save you time and effort.
+* How Variable Arguments are Used::     An overview of the facilities for
+                                        receiving variable arguments.
+* Variable Arguments Interface::        Detailed specification of the
                                         library facilities.
-* Example of Variable Arguments::      A complete example.
+* Example of Variable Arguments::       A complete example.
 @end menu
 
-@node Why Variable Arguments are Used
+@node Why Variable Arguments are Used, How Variable Arguments are Used,  , Variable Argument Facilities
 @section Why Variable Arguments are Used
 
-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.
+Most C functions take a fixed number of arguments.  When you define a
+function, you also supply a specific data type for each argument.
+Every call to the function should supply the same number and type of
+arguments as specified in the function definition.
 
-On the other hand, sometimes a function performs an operation that makes
-sense no matter how many arguments it is called with.  
+On the other hand, sometimes a function performs an operation that can
+meaningfully accept an unlimited number of arguments.  
 
 For example, consider a function that joins its arguments into a linked
 list.  It makes sense to connect any number of arguments together into a
@@ -53,73 +52,75 @@ example of still another class of function where variable arguments are
 useful.  This function prints its arguments (which can vary in type as
 well as number) under the control of a format template string.
 
-@node How Variable Arguments are Used
+@node How Variable Arguments are Used, Variable Arguments Interface, Why Variable Arguments are Used, Variable Argument Facilities
 @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
-                                        with variable arguments.
-* Receiving the Argument Values::      Steps you must follow to access the
+* Syntax for Variable Arguments::       How to make a prototype for a
+                                         function with variable arguments.
+* Receiving the Argument Values::       Steps you must follow to access the
                                         optional argument values.
-* How Many Arguments::                 How to decide whether there are more
+* How Many Arguments::                  How to decide whether there are more
                                         arguments.
-* Calling Variadic Functions::         Things you need to know about calling
+* Calling Variadic Functions::          Things you need to know about calling
                                         variable arguments functions.
 @end menu
 
-@node Syntax for Variable Arguments
+@node Syntax for Variable Arguments, Receiving the Argument Values,  , How Variable Arguments are Used
 @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{}
+int 
+func (const char *a, int b, @dots{})
+@{
+  @dots{}
+@}     
 @end example
 
 @noindent
-begins a definition of a function @code{func} which returns an
+outlines a definition of a function @code{func} which returns an
 @code{int} and takes at least two arguments, the first two being a
 @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, and may not be, 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.
-In particular, the @samp{@dots{}} syntax is a new feature of ANSI C.
+but incompatible, mechanism for defining functions with variable numbers
+of arguments.  In particular, the @samp{@dots{}} syntax is a new feature
+of ANSI C.
 
 
-@node Receiving the Argument Values
+@node Receiving the Argument Values, How Many Arguments, Syntax for Variable Arguments, How Variable Arguments are Used
 @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 function, to access the optional
+arguments with the following three step process:
 
 @enumerate
 @item
-A variable of type @code{va_list} is initialized using @code{va_start}.
+You initialize an argument pointer 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,23 +135,21 @@ 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
+@node How Many Arguments, Calling Variadic Functions, Receiving the Argument Values, How Variable Arguments are Used
 @subsection How Many Arguments Were Supplied
 
 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.
+the value of one of the required arguments is used to tell the function
+this information.  It is up to you to define an 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 convention is usable 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,20 +164,21 @@ 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
+@node Calling Variadic Functions,  , How Many Arguments, How Variable Arguments are Used
 @subsection Calling Variadic Functions
 
-Functions that are @emph{defined} to be variadic also be @emph{declared}
-to be variadic using a function prototype in the scope of all calls to
-it.  This is because C compilers might use a different internal function
-call protocol for variadic functions than for functions that take a
-fixed number and type of arguments.  If the compiler can't determine in
-advance that the function being called is variadic, it may end up trying
-to call it incorrectly and your program won't work.
+Functions that are @emph{defined} to be variadic must also be
+@emph{declared} to be variadic using a function prototype in the scope
+of all calls to it.  This is because C compilers might use a different
+internal function call protocol for variadic functions than for
+functions that take a fixed number and type of arguments.  If the
+compiler can't determine in advance that the function being called is
+variadic, it may end up trying to call it incorrectly and your program
+won't work.
 @cindex function prototypes
 @cindex prototypes for variadic functions
 @cindex variadic functions need prototypes
@@ -186,7 +186,7 @@ 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
+type @code{char} or @code{short int} (whether signed or not) 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
@@ -199,50 +199,64 @@ corresponding formal parameters).
 @cindex default argument promotions
 @cindex argument promotion
 
-@node Variable Arguments Interface
+@node Variable Arguments Interface, Example of Variable Arguments, How Variable Arguments are Used, Variable Argument Facilities
 @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
 @deftp {Data Type} va_list
-The type @code{va_list} is used to represent a list of an
-unknown number of arguments of unknown types.@refill
+The type @code{va_list} is used for argument pointer variables.
 @end deftp
 
+@comment stdarg.h
+@comment ANSI
 @deftypefn {Macro} void va_start (va_list @var{ap}, @var{last_required})
-This macro initializes the variable @var{ap} to hold the list of
-optional arguments supplied to the function; @var{last_required} must be
-the last required argument parameter to the function.  Initially, @var{ap}
-``points to'' the first optional argument.
+This macro initialized the argument pointer variable @var{ap} to point
+to the first of the optional arguments of the current function;
+@var{last_required} must be the last required argument to the function.
 @end deftypefn
 
+@comment stdarg.h
+@comment ANSI
 @deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type})
 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.
+Thus, successive uses of @code{va_arg} return successive optional 
+arguments.
 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} may 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
 
 
-@node Example of Variable Arguments
+@node Example of Variable Arguments,  , Variable Arguments Interface, Variable Argument Facilities
 @section Example of Variable Arguments
 
-Here is a full example of a function using these macros.  The first 
-argument to the function is the count of remaining arguments, which
-are added up and the result returned.  (This is obviously a rather
-pointless function, but it serves to illustrate the way the variable
-arguments facility is commonly used.)
+Here is a complete sample function that accepts variable numbers of
+arguments.  The first argument to the function is the count of remaining
+arguments, which are added up and the result returned.  (This is
+obviously a rather pointless function, but it serves to illustrate the
+way the variable arguments facility is commonly used.)
 
 @comment Yes, this example has been tested.
 
@@ -258,18 +272,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