DESCRIPTION

     A function may be called with a varying number of  arguments
     of varying types.  The include file stdarg.h declares a type
     va_list and defines three macros for stepping through a list
     of  arguments  whose  number  and types are not known to the
     called function.

     The called function 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.

     The parameter last is the name of the last parameter  before
     the  variable  argument  list,  i.e.,  the last parameter of
     which the calling function knows the type.

     Because the  address  of  this  parameter  is  used  in  the
     va_start  macro,  it  should  not  be declared as a register
     variable, or as a function or an array type.

     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 argument 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 invoca-
     tions return the values of the remaining arguments.

     The va_end macro handles a normal return from  the  function
     whose variable 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 charac-
     ter based on the type.
          void foo(char *fmt, ...)
          {
               va_list ap;
               int d;
               char c, *p, *s;

               va_start(ap, fmt);
               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);
          }

STANDARDS

     The va_start, va_arg, and  va_end  macros  conform  to  ANSI
     C3.159-1989 (``ANSI C'').

COMPATIBILITY

     These macros are not compatible  with  the  historic  macros
     they replace.  A backward compatible version can be found in
     the include file varargs.h.

BUGS

     Unlike the varargs macros, the stdarg macros do  not  permit
     programmers  to  code  a  function  with no fixed arguments.
     This problem generates work mainly when  converting  varargs
     code  to  stdarg  code, but it also creates difficulties for
     variadic functions that wish to pass all of their  arguments
     on  to  a  function  that  takes a va_list argument, such as
     vfprintf(3).