aboutsummaryrefslogtreecommitdiff
path: root/manual/=stdarg.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/=stdarg.texi')
-rw-r--r--manual/=stdarg.texi290
1 files changed, 0 insertions, 290 deletions
diff --git a/manual/=stdarg.texi b/manual/=stdarg.texi
deleted file mode 100644
index a209efc..0000000
--- a/manual/=stdarg.texi
+++ /dev/null
@@ -1,290 +0,0 @@
-@node Variable Argument Facilities, Memory Allocation, Common Definitions, Top
-@chapter Variable Argument Facilities
-@cindex variadic argument functions
-@cindex variadic functions
-@cindex variable number of arguments
-@cindex optional arguments
-
-@w{ISO 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 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:: 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.
-@end menu
-
-@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 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 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
-list of arbitrary length. Without facilities for variable arguments,
-you would have to define a separate function for each possible number of
-arguments you might want to link together. This is an example of a
-situation where some kind of mapping or iteration is performed over an
-arbitrary number of arguments of the same type.
-
-Another kind of application where variable arguments can be useful is
-for functions where values for some arguments can simply be omitted in
-some calls, either because they are not used at all or because the
-function can determine appropriate defaults for them if they're missing.
-
-The library function @code{printf} (@pxref{Formatted Output}) is an
-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, Variable Arguments Interface, Why Variable Arguments are Used, Variable Argument Facilities
-@section How Variable Arguments are Used
-
-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
- optional argument values.
-* How Many Arguments:: How to decide whether there are more
- arguments.
-* Calling Variadic Functions:: Things you need to know about calling
- variable arguments functions.
-@end menu
-
-@node Syntax for Variable Arguments, Receiving the Argument Values, , How Variable Arguments are Used
-@subsection Syntax for Variable Arguments
-
-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
-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 @w{ISO C} standard is that the last
-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 functions with variable numbers
-of arguments. In particular, the @samp{@dots{}} syntax is a new feature
-of @w{ISO C}.
-
-
-@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 function, to access the optional
-arguments with the following three step process:
-
-@enumerate
-@item
-You initialize an argument pointer variable of type @code{va_list} using
-@code{va_start}.
-
-@item
-You access the optional arguments by successive calls to @code{va_arg}.
-
-@item
-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
-accept variable arguments. However, you can pass the @code{va_list}
-variable as an argument to another function and perform all or part of
-step 2 there. After doing this, the value of the @code{va_list}
-variable in the calling function becomes undefined for further calls to
-@code{va_arg}; you should just pass it to @code{va_end}.
-
-You can perform the entire sequence of the three steps multiple times
-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 too 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 tell the function
-this information. It is up to you to define an appropriate calling
-convention for each function, and write all calls accordingly.
-
-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
-argument to @code{printf} is one example of this.
-
-A similar technique that is sometimes used is to have one of the
-required arguments be a bit mask, with a bit for each possible optional
-argument that might be supplied. The bits are tested in a predefined
-sequence; if the bit is set, the value of the next argument is
-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 indicate the end of the argument list, provided that a null
-pointer isn't otherwise meaningful to the function.
-
-
-@node Calling Variadic Functions, , How Many Arguments, How Variable Arguments are Used
-@subsection Calling Variadic Functions
-
-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
-
-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} (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
-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
-corresponding formal parameters).
-@cindex default argument promotions
-@cindex argument promotion
-
-@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}.
-@pindex stdarg.h
-
-@comment stdarg.h
-@comment ISO
-@deftp {Data Type} va_list
-The type @code{va_list} is used for argument pointer variables.
-@end deftp
-
-@comment stdarg.h
-@comment ISO
-@deftypefn {Macro} void va_start (va_list @var{ap}, @var{last_required})
-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 ISO
-@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.
-
-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 ISO
-@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} 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.
-
-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, , Variable Arguments Interface, Variable Argument Facilities
-@section Example of Variable Arguments
-
-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.
-
-@example
-#include <stdarg.h>
-
-int
-add_em_up (int count, @dots{})
-@{
- va_list ap;
- int i, sum;
-
- va_start (ap, count); /* @r{Initialize the argument list.} */
-
- sum = 0;
- 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;
-@}
-
-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