NAME

       stdarg.h - handle variable argument list

SYNOPSIS

       #include <stdarg.h>

       void va_start(va_list ap, argN);
       void va_copy(va_list dest, va_list src);
       type va_arg(va_list ap, type);
       void va_end(va_list ap);

DESCRIPTION

       The  <stdarg.h>  header shall contain a set of macros which allows portable functions that
       accept variable argument lists to be written. Functions that have variable argument  lists
       (such  as  printf()) but do not use these macros are inherently non-portable, as different
       systems use different argument-passing conventions.

       The type va_list shall be defined for variables used to traverse the list.

       The va_start() macro is invoked to initialize ap to the beginning of the list  before  any
       calls to va_arg().

       The va_copy() macro initializes dest as a copy of src, as if the va_start() macro had been
       applied to dest followed by the same sequence  of  uses  of  the  va_arg()  macro  as  had
       previously  been  used  to  reach  the  present  state  of  src. Neither the va_copy() nor
       va_start() macro shall be invoked to reinitialize dest without an  intervening  invocation
       of the va_end() macro for the same dest.

       The  object  ap may be passed as an argument to another function; if that function invokes
       the va_arg() macro with parameter  ap,  the  value  of  ap  in  the  calling  function  is
       unspecified  and  shall  be passed to the va_end() macro prior to any further reference to
       ap. The parameter argN is the identifier  of  the  rightmost  parameter  in  the  variable
       parameter  list in the function definition (the one just before the ...). If the parameter
       argN is declared with the register storage class, with a function type or array  type,  or
       with  a  type  that  is not compatible with the type that results after application of the
       default argument promotions, the behavior is undefined.

       The va_arg() macro shall return the next argument in the  list  pointed  to  by  ap.  Each
       invocation of va_arg() modifies ap so that the values of successive arguments are returned
       in turn. The type parameter shall be a type name specified such that the type of a pointer
       to  an  object  that  has the specified type can be obtained simply by postfixing a '*' to
       type. If there is no actual next argument, or if type is not compatible with the  type  of
       the  actual  next argument (as promoted according to the default argument promotions), the
       behavior is undefined, except for the following cases:

        * One type is a signed integer type, the other type is the corresponding unsigned integer
          type, and the value is representable in both types.

        * One type is a pointer to void and the other is a pointer to a character type.

        * Both types are pointers.

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

       The va_end() macro is used to clean up; it invalidates ap for use  (unless  va_start()  or
       va_copy() is invoked again).

       Each invocation of the va_start() and va_copy() macros shall be matched by a corresponding
       invocation of the va_end() macro in the same function.

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

EXAMPLES

       This example is a possible implementation of execl():

              #include <stdarg.h>

              #define  MAXARGS     31

              /*
               * execl is called by
               * execl(file, arg1, arg2, ..., (char *)(0));
               */
              int execl(const char *file, const char *args, ...)
              {
                  va_list ap;
                  char *array[MAXARGS +1];
                  int argno = 0;

                  va_start(ap, args);
                  while (args != 0 && argno < MAXARGS)
                  {
                      array[argno++] = args;
                      args = va_arg(ap, const char *);
                  }
                  array[argno] = (char *) 0;
                  va_end(ap);
                  return execv(file, array);
              }

       The following sections are informative.

APPLICATION USAGE

       It is up to the calling routine to communicate to the called routine  how  many  arguments
       there are, since it is not always possible for the called routine to determine this in any
       other way.  For example, execl() is passed a null pointer to signal the end of  the  list.
       The printf() function can tell how many arguments are there by the format argument.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       The System Interfaces volume of IEEE Std 1003.1-2001, exec, printf()

COPYRIGHT

       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable  Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .