Manual Pages for UNIX Operating System command usage for man stdarg

Extended Library Functions                           stdarg(3EXT)



NAME
     stdarg - handle variable argument list

SYNOPSIS
     #include 
     va_list pvar;

     void va_start(va_list pvar, void name);


     (type *) va_arg(va_list pvar, type);


     void va_copy(va_list dest, va_list src);


     void va_end(va_list pvar);


DESCRIPTION
     This set of macros allows portable  procedures  that  accept
     variable  numbers of arguments of variable types to be writ-
     ten. Routines that have variable  argument  lists  (such  as
     printf)  but  do not use stdarg are inherently non-portable,
     as different machines use different argument-passing conven-
     tions.


     va_list is a type defined for the variable used to  traverse
     the list.


     The va_start macro is  invoked  before  any  access  to  the
     unnamed arguments and initializes pvar for subsequent use by
     va_arg() and va_end(). The parameter name is the  identifier
     of the rightmost parameter in the variable parameter list in
     the function definition (the one just before the , ...).  If
     this  parameter  is declared with the register storage class
     or with a function 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 parameter name is required under strict ANSI C  compila-
     tion.  In other compilation modes, name need not be supplied
     and the second parameter to the va_start() macro can be left
     empty (for example, va_start(pvar, );). This allows for rou-
     tines that contain no parameters before the ... in the vari-
     able parameter list.






SunOS 5.11          Last change: 22 Mar 2006                    1






Extended Library Functions                           stdarg(3EXT)



     The va_arg() macro expands to an  expression  that  has  the
     type and value of the next argument in the call. The parame-
     ter  pvar  should  have  been  previously   initialized   by
     va_start().  Each  invocation  of  va_arg() modifies pvar so
     that the values of  successive  arguments  are  returned  in
     turn.  The parameter type is the type name of the next argu-
     ment to be returned. The type name must be specified in such
     a  way  so  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.


     The va_copy() macro  saves  the  state  represented  by  the
     va_listsrc  in  the va_list dest. The va_list passed as dest
     should not be initialized by a previous call to  va_start(),
     and  must  be  passed  to  va_end() before being reused as a
     parameter to va_start() or as the dest parameter of a subse-
     quent  call  to  va_copy(). The behavior is undefined should
     any of these restrictions not be met.


     The va_end() macro is used to clean up.


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

EXAMPLES
     Example 1 A sample program.


     This example gathers into an array a list of arguments  that
     are  pointers  to  strings  (but not more than MAXARGS argu-
     ments) with function f1, then passes the array as  a  single
     argument to function f2. The number of pointers is specified
     by the first argument to f1.


       #include 
       #define MAXARGS     31
       void f1(int n_ptrs, ...)
       {
            va_list ap;
            char *array[MAXARGS];
            int ptr_no = 0;

            if (n_ptrs > MAXARGS)
                 n_ptrs = MAXARGS;
            va_start(ap, n_ptrs);



SunOS 5.11          Last change: 22 Mar 2006                    2






Extended Library Functions                           stdarg(3EXT)



            while (ptr_no < n_ptrs)
                 array[ptr_no++] = va_arg(ap, char*);
            va_end(ap);
            f2(n_ptrs, array);
       }



     Each call to f1 shall have visible  the  definition  of  the
     function or a declaration such as


       void f1(int, ...)



ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


SEE ALSO
     vprintf(3C), attributes(5), standards(5)

NOTES
     It is the responsibility of the calling routine  to  specify
     in some manner how many arguments there are, since it is not
     always possible to determine the number  of  arguments  from
     the stack frame. For example, execl is passed a zero pointer
     to signal the end of  the  list.  The  printf  function  can
     determine  the number of arguments by the format. It is non-
     portable to specify a second argument  of  char,  short,  or
     float  to  va_arg(),  because  arguments  seen by the called
     function are not char, short, or float. C converts char  and
     short  arguments to int and converts float arguments to dou-
     ble before passing them to a function.









SunOS 5.11          Last change: 22 Mar 2006                    3