Provided by: manpages-posix-dev_2.16-1_all bug

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 .