varargs(3)
- NetBSD Manual Pages
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.1 February 4, 2002 NetBSD 5.0.1
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.