NAME

     stdarg - variable argument list


SYNOPSIS

     #include <stdarg.h>

     void va_start(va_list ap, argtypeN parmN)
     type va_arg(va_list ap, type)
     void va_end(va_list ap)


DESCRIPTION

     This set of macros provides a means of writing portable pro-
     cedures  that accept variable argument lists.  Routines hav-
     ing variable argument lists (such as printf(3)) that do  not
     use  stdarg  are  inherently  nonportable,  since  different
     machines use different argument passing conventions.

     A function that accepts a variable argument list is declared
     with  "..."  at the end of its parameter list.  It must have
     at least one normal argument before the "...".  For example:

          int printf(const char *format, ...) { /* code */ }
          int fprintf(FILE *stream, const char *format, ...) { /* code */ }

     va_list is a type which is used for the variable  ap  within
     the  body  of  a variable argument function which is used to
     traverse the list.

     va_start(ap, parmN) is called to initialize ap to the begin-
     ning  of the list.  The last true parameter of the function,
     parmN, must be supplied to allow  va_start  to  compute  the
     address of the first variable parameter.

     va_arg(ap, type) will return the next argument in  the  list
     pointed  to  by  ap.  Type is the type to which the expected
     argument will be converted when passed as an argument.

     Different types can be mixed, but it is up to the routine to
     know  what  type of argument is expected, since it cannot be
     determined at runtime.

     va_end(ap) must be used to finish up.

     Multiple traversals, each bracketed by va_start ...  va_end,
     are possible.


EXAMPLE

         #include <stdarg.h>
         execl(const char *path, ...)
         {
             va_list ap;
             char *args[100];
             int argno = 0;

             va_start(ap, path);
             while ((args[argno++] = va_arg(ap, char *)) != NULL) {}
             va_end(ap);
             return execv(path, args);
         }


NOTES

     It is up to the calling routine to determine how many  argu-
     ments  there are, since it is not possible to determine this
     from the stack frame.  For  example,  execl  passes  a  null
     pointer  to signal the end of the list.  Printf can tell how
     many arguments are supposed to be there by the format.

     The macros va_start and va_end may be  arbitrarily  complex;
     for  example, va_start might contain an opening brace, which
     is closed by a matching brace in va_end.  Thus, they  should
     only be used where they could be placed within a single com-
     plex statement.


BUGS

     It is impossible to properly show the macros as  C  declara-
     tions  as  is done in the synopsis.  They can never be coded
     as C functions, because all three macros use their arguments
     by  address,  and  the  type  field is certainly impossible.
     Just look at them as being part  of  the  C  language,  like
     sizeof.