stdarg.h(3)                POSIX Programmer's Manual               stdarg.h(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       stdarg.h -- handle variable argument list

SSYYNNOOPPSSIISS
       #include <stdarg.h>

       void va_start(va_list _a_p, _a_r_g_N);
       void va_copy(va_list _d_e_s_t, va_list _s_r_c);
       _t_y_p_e va_arg(va_list _a_p, _t_y_p_e);
       void va_end(va_list _a_p);

DDEESSCCRRIIPPTTIIOONN
       The functionality described on this reference page is aligned with the
       ISO C standard. Any conflict between the requirements described here
       and the ISO C standard is unintentional. This volume of POSIX.1-2008
       defers to the ISO C standard.

       The _<_s_t_d_a_r_g_._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 _p_r_i_n_t_f()) but do
       not use these macros are inherently non-portable, as different systems
       use different argument-passing conventions.

       The _<_s_t_d_a_r_g_._h_> header shall define the vvaa__lliisstt type for variables used
       to traverse the list.

       The _v_a___s_t_a_r_t() macro is invoked to initialize _a_p to the beginning of
       the list before any calls to _v_a___a_r_g().

       The _v_a___c_o_p_y() macro initializes _d_e_s_t as a copy of _s_r_c, as if the
       _v_a___s_t_a_r_t() macro had been applied to _d_e_s_t followed by the same sequence
       of uses of the _v_a___a_r_g() macro as had previously been used to reach the
       present state of _s_r_c.  Neither the _v_a___c_o_p_y() nor _v_a___s_t_a_r_t() macro shall
       be invoked to reinitialize _d_e_s_t without an intervening invocation of
       the _v_a___e_n_d() macro for the same _d_e_s_t.

       The object _a_p may be passed as an argument to another function; if that
       function invokes the _v_a___a_r_g() macro with parameter _a_p, the value of _a_p
       in the calling function is unspecified and shall be passed to the
       _v_a___e_n_d() macro prior to any further reference to _a_p.  The parameter
       _a_r_g_N is the identifier of the rightmost parameter in the variable
       parameter list in the function definition (the one just before the
       ...). If the parameter _a_r_g_N is declared with the rreeggiisstteerr 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 _v_a___a_r_g() macro shall return the next argument in the list pointed
       to by _a_p.  Each invocation of _v_a___a_r_g() modifies _a_p so that the values
       of successive arguments are returned in turn. The _t_y_p_e 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 _t_y_p_e 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 vvooiidd 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 _v_a___e_n_d() macro is used to clean up; it invalidates _a_p for use
       (unless _v_a___s_t_a_r_t() or _v_a___c_o_p_y() is invoked again).

       Each invocation of the _v_a___s_t_a_r_t() and _v_a___c_o_p_y() macros shall be matched
       by a corresponding invocation of the _v_a___e_n_d() macro in the same
       function.

       Multiple traversals, each bracketed by _v_a___s_t_a_r_t() ...  _v_a___e_n_d(), are
       possible.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       This example is a possible implementation of _e_x_e_c_l():

           ##iinncclluuddee <<ssttddaarrgg..hh>>

           #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);
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       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, _e_x_e_c_l()
       is passed a null pointer to signal the end of the list. The _p_r_i_n_t_f()
       function can tell how many arguments are there by the _f_o_r_m_a_t argument.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       The System Interfaces volume of POSIX.1-2008, _e_x_e_c, _f_p_r_i_n_t_f()

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                          stdarg.h(3)
