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.1                     February 4, 2002                     NetBSD 5.1