varargs(3) - NetBSD Manual Pages

Command: Section: Arch: Collection:  
VARARGS(3)              NetBSD Library Functions Manual             VARARGS(3)


NAME
varargs -- variable argument lists
SYNOPSIS
#include <varargs.h> void va_start(va_list ap); type va_arg(va_list ap, type); void va_end(va_list ap);
DESCRIPTION
These historic interfaces are provided to support compilation of existing programs only. New code should use the stdarg(3) interfaces. A function may be called with a varying number of arguments of varying types. The include file <varargs.h> declares a type (va_list) and defines three macros for stepping through a list of arguments whose num- ber and types are not known to the called function. The called function must name an argument va_alist, which marks the start of the variable argument list, and which is naturally the last argument named. It is declared by va_dcl, which should not be followed by a semi- colon. The called function also must declare an object of type va_list which is used by the macros va_start(), va_arg(), and va_end(). The va_start() macro initializes ap for subsequent use by va_arg() and va_end(), and must be called first. It is possible for va_alist to be the only parameter to a function, resulting in it being possible for a function to have no fixed arguments preceding the variable argument list. The va_start() macro returns no value. The va_arg() macro expands to an expression that has the type and value of the next argument in the call. The parameter ap is the va_list ap initialized by va_start(). Each call to va_arg() modifies ap so that the next call returns the next argument. The parameter type is a type name specified so that the type of a pointer to an object that has the speci- fied type can be obtained simply by adding a * to type. If there is no next argument, or if type is not compatible with the type of the actual next argument (as promoted according to the default argu- ment promotions), random errors will occur. The first use of the va_arg() macro after that of the va_start() macro returns the argument after last. Successive invocations return the val- ues of the remaining arguments. The va_end() macro handles a normal return from the function whose vari- able argument list was initialized by va_start(). The va_end() macro returns no value.
EXAMPLES
The function foo takes a string of format characters and prints out the argument associated with each format character based on the type. void foo(fmt, va_alist) char *fmt; va_dcl { va_list ap; int d; char c, *p, *s; va_start(ap); while (*fmt) { switch (*fmt++) { case 's': /* string */ s = va_arg(ap, char *); printf("string %s\n", s); break; case 'd': /* int */ d = va_arg(ap, int); printf("int %d\n", d); break; case 'c': /* char */ c = va_arg(ap, char); printf("char %c\n", c); break; } } va_end(ap); }
SEE ALSO
stdarg(3)
STANDARDS
These historic macros were replaced in ANSI X3.159-1989 (``ANSI C89'') by the include file <stdarg.h>; see stdarg(3) for its description.
COMPATIBILITY
These macros are not compatible with the new macros they were replaced by. In particular, it is not possible for a stdarg function to have no fixed arguments. NetBSD 5.0 February 4, 2002 NetBSD 5.0
Powered by man-cgi (2021-06-01). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.