glibc/manual/=stdarg.texi
Ulrich Drepper f65fd747b4 update from main archive 961207
Sun Dec  8 06:56:49 1996  Ulrich Drepper  <drepper@cygnus.com>

	* io/getwd.c: Use PATH_MAX not LOCAL_PATH_MAX.  Fix typo in
	comment.
	* stdlib/canonicalize.c: Correct bugs in last change.
	Patch by HJ Lu.

	* libio/Makefile (routines): Remove ioprims.
	(aux): Remove cleanup.
	Add IO_DEBUG option for .o files.
	* libio/cleanups.c: Removed.
	* libio/ioprims.c: Removed.
	* libio/filedoalloc.c: More updates from libg++-2.8b5.
	* libio/fileops.c: Likewise.
	* libio/genops.c: Likewise.
	* libio/iolibio.h: Likewise.
	* libio/iopopen.c: Likewise.
	* libio/iovsprintf.c: Likewise.
	* libio/iovsscanf.c: Likewise.
	* libio/libio.h: Likewise.
	* libio/libioP.h: Likewise.
	* libio/memstream.c: Likewise.
	* libio/strfile.h: Likewise.
	* libio/vasprintf.c: Likewise.
	* libio/vsnprintf.c: Likewise.

	* libio/stdio.h: Define P_tmpdir only is __USE_SVID.

	* manual/arith.texi: Change references to ANSI C to ISO C.
	* manual/conf.texi: Likewise.
	* manual/creature.texi: Likewise.
	* manual/ctype.texi: Likewise.
	* manual/errno.texi: Likewise.
	* manual/filesys.texi: Likewise.
	* manual/intro.texi. Likewise.
	* manual/io.texi: Likewise.
	* manual/lang.texi: Likewise.
	* manual/libc.texinfo: Likewise.
	* manual/locale.texi: Likewise.
	* manual/maint.texi: Likewise.
	* manual/mbyte.texi: Likewise.
	* manual/memory.texi: Likewise.
	* manual/process.texi: Likewise.
	* manual/process.texi: Likewise.
	* manual/search.texi: Likewise.
	* manual/setjmp.texi: Likewise.
	* manual/signal.texi: Likewise.
	* manual/startup.texi: Likewise.
	* manual/stdio.texi: Likewise.
	* manual/string.texi: Likewise.
	* manual/time.texi: Likewise.

	* manual/locale.texi: Remove description of LC_RESPONSE and add
	LC_MESSAGES.

	* Makefile (subdirs): Change malloc in $(malloc).
	* config.make.in: Add variable malloc which is initialized from
	@malloc@.
	* configure.in: Add new option --enable-new-malloc to use new
	malloc.  This is the default on Linux.
	* sysdeps/unix/sysv/linux/configure.in: Define malloc to new-malloc
	by default.
	* new-malloc/Makefile: New file.  Improved malloc implementation.
	* new-malloc/malloc.c: Likewise.
	* new-malloc/malloc.h: Likewise.
	* new-malloc/mallocbug.c: Likewise.
	* new-malloc/obstack.c: Likewise.
	* new-malloc/obstack.h: Likewise.
	* new-malloc/thread-m.h: Likewise.
	* time/Makefile: Compile ap.c with NO_MCHECK flag for now.
	* time/ap.c: Don't call mcheck if NO_MCHECK is defined.

	* resolv/Makefile: Add rule to rebuiild libresolv.so when libc.so
	changed.

	* stdio/feof.c: Update copyright.
	* stdio/stdio.h: Add field for lock to FILE structure.
	Add cast to *MAGIC constants to prevent warnings.

	* stdio-common/bug7.c: Correct test.  Stream must not be closed
	twice.

	* stdlib/Makefile (routines): Add secure-getenv.
	* stdlib/secure-getenv.c: New file.  __secure_getenv function
	moved to here from sysdeps/generic/getenv.c.  Otherwise an
	application cannot replace the getenv function in the libc.
	* sysdeps/generic/getenv.c: Remove __secure_getenv function.
	* sysdeps/stub/getenv.c: Remove __secure_getenv alias.

	* sysdeps/mach/libc-lock.h: Define__libc_mutex_lock to __mutex_lock.

	* sysdeps/posix/fdopen.c: Update copyright.  Don't use EXFUN.

	* time/test-tz.c: Comment fifth test out.  PROBLEM.

	* time/tzset.c: De-ANSI-declfy.
	(__tzset): Don't increment pointer tz when no DST information is
	given.

Sat Dec  7 23:47:54 1996  Ulrich Drepper  <drepper@cygnus.com>

	* sysdeps/mach/libc-lock.h [_LIBC]: Add definition of
	__libc_mutex_lock.
	Patch by Thomas Bushnell.

	* sysdeps/unix/sysv/linux/timebits.h: Load <asm/param.h> only
	if __USE_MISC.

	* sysdeps/unix/sysv/linux/Dist: Add llseek.c.

Sat Dec  7 12:18:56 1996  Ulrich Drepper  <drepper@cygnus.com>

	* time/strftime (%c format): Remove %Z from default string.
	Reported by Paul Eggert

	* io/getwd.c: Don't apply getcwd on user supplied buffer.
1996-12-08 08:01:13 +00:00

291 lines
12 KiB
Plaintext

@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