1stdarg(3EXT)              Extended Library Functions              stdarg(3EXT)
2
3
4

NAME

6       stdarg - handle variable argument list
7

SYNOPSIS

9       #include <stdarg.h>
10       va_list pvar;
11
12       void va_start(va_list pvar, void name);
13
14
15       (type *) va_arg(va_list pvar, type);
16
17
18       void va_copy(va_list dest, va_list src);
19
20
21       void va_end(va_list pvar);
22
23

DESCRIPTION

25       This set of macros allows portable procedures that accept variable num‐
26       bers of arguments of variable types to be written. Routines  that  have
27       variable  argument  lists  (such  as  printf) but do not use stdarg are
28       inherently non-portable, as different machines use different  argument-
29       passing conventions.
30
31
32       va_list is a type defined for the variable used to traverse the list.
33
34
35       The  va_start  macro  is invoked before any access to the unnamed argu‐
36       ments and initializes pvar for subsequent use by va_arg() and va_end().
37       The  parameter name is the identifier of the rightmost parameter in the
38       variable parameter list in the function definition (the one just before
39       the  ,  ...).  If  this parameter is declared with the register storage
40       class or with a function or array type, or with a type that is not com‐
41       patible  with  the  type  that results after application of the default
42       argument promotions, the behavior is undefined.
43
44
45       The parameter name is required under  strict  ANSI  C  compilation.  In
46       other  compilation  modes,  name  need  not  be supplied and the second
47       parameter to the va_start() macro  can  be  left  empty  (for  example,
48       va_start(pvar, );). This allows for routines that contain no parameters
49       before the ... in the variable parameter list.
50
51
52       The va_arg() macro expands to an expression that has the type and value
53       of  the  next argument in the call. The parameter pvar should have been
54       previously initialized by va_start(). Each invocation of va_arg() modi‐
55       fies  pvar  so  that the values of successive arguments are returned in
56       turn. The parameter type is the type name of the next  argument  to  be
57       returned.  The  type  name  must be specified in such a way so that the
58       type of a pointer to an object that  has  the  specified  type  can  be
59       obtained  simply  by postfixing a * to type. If there is no actual next
60       argument, or if type is not compatible with the type of the actual next
61       argument  (as  promoted  according to the default argument promotions),
62       the behavior is undefined.
63
64
65       The va_copy() macro saves the state represented by  the  va_listsrc  in
66       the  va_list dest. The va_list passed as dest should not be initialized
67       by a previous call to va_start(), and must be passed to va_end() before
68       being reused as a parameter to va_start() or as the dest parameter of a
69       subsequent call to va_copy(). The behavior is undefined should  any  of
70       these restrictions not be met.
71
72
73       The va_end() macro is used to clean up.
74
75
76       Multiple  traversals,  each  bracketed  by va_start() and va_end(), are
77       possible.
78

EXAMPLES

80       Example 1 A sample program.
81
82
83       This example gathers into an array a list of arguments that are  point‐
84       ers  to strings (but not more than MAXARGS arguments) with function f1,
85       then passes the array as a single argument to function f2.  The  number
86       of pointers is specified by the first argument to f1.
87
88
89         #include <stdarg.h>
90         #define MAXARGS     31
91         void f1(int n_ptrs, ...)
92         {
93              va_list ap;
94              char *array[MAXARGS];
95              int ptr_no = 0;
96
97              if (n_ptrs > MAXARGS)
98                   n_ptrs = MAXARGS;
99              va_start(ap, n_ptrs);
100              while (ptr_no < n_ptrs)
101                   array[ptr_no++] = va_arg(ap, char*);
102              va_end(ap);
103              f2(n_ptrs, array);
104         }
105
106
107
108       Each  call to f1 shall have visible the definition of the function or a
109       declaration such as
110
111
112         void f1(int, ...)
113
114
115

ATTRIBUTES

117       See attributes(5) for descriptions of the following attributes:
118
119
120
121
122       ┌─────────────────────────────┬─────────────────────────────┐
123       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
124       ├─────────────────────────────┼─────────────────────────────┤
125       │Interface Stability          │Standard                     │
126       └─────────────────────────────┴─────────────────────────────┘
127

SEE ALSO

129       vprintf(3C), attributes(5), standards(5)
130

NOTES

132       It is the responsibility of the calling routine to specify in some man‐
133       ner  how  many  arguments there are, since it is not always possible to
134       determine the number of arguments from the stack  frame.  For  example,
135       execl  is  passed  a  zero  pointer  to signal the end of the list. The
136       printf function can determine the number of arguments by the format. It
137       is  non-portable  to specify a second argument of char, short, or float
138       to va_arg(), because arguments seen by  the  called  function  are  not
139       char,  short,  or float. C converts char and short arguments to int and
140       converts float arguments to double before passing them to a function.
141
142
143
144SunOS 5.11                        22 Mar 2006                     stdarg(3EXT)
Impressum