1<stdarg.h>(0P) POSIX Programmer's Manual <stdarg.h>(0P)
2
6 stdarg.h - handle variable argument list
7
9 #include <stdarg.h>
10 void va_start(va_list ap, argN);
12 void va_copy(va_list dest, va_list src);
13 type va_arg(va_list ap, type);
14 void va_end(va_list ap);
15
18 The <stdarg.h> header shall contain a set of macros which allows porta‐
19 ble functions that accept variable argument lists to be written. Func‐
20 tions that have variable argument lists (such as printf()) but do not
21 use these macros are inherently non-portable, as different systems use
22 different argument-passing conventions.
23 The type va_list shall be defined for variables used to traverse the
25 list.
26 The va_start() macro is invoked to initialize ap to the beginning of
28 the list before any calls to va_arg().
29 The va_copy() macro initializes dest as a copy of src, as if the
31 va_start() macro had been applied to dest followed by the same sequence
32 of uses of the va_arg() macro as had previously been used to reach the
33 present state of src. Neither the va_copy() nor va_start() macro shall
34 be invoked to reinitialize dest without an intervening invocation of
35 the va_end() macro for the same dest.
36 The object ap may be passed as an argument to another function; if that
38 function invokes the va_arg() macro with parameter ap, the value of ap
39 in the calling function is unspecified and shall be passed to the
40 va_end() macro prior to any further reference to ap. The parameter argN
41 is the identifier of the rightmost parameter in the variable parameter
42 list in the function definition (the one just before the ...). If the
43 parameter argN is declared with the register storage class, with a
44 function type or array type, or with a type that is not compatible with
45 the type that results after application of the default argument promo‐
46 tions, the behavior is undefined.
47 The va_arg() macro shall return the next argument in the list pointed
49 to by ap. Each invocation of va_arg() modifies ap so that the values of
50 successive arguments are returned in turn. The type parameter shall be
51 a type name specified such that the type of a pointer to an object that
52 has the specified type can be obtained simply by postfixing a '*' to
53 type. If there is no actual next argument, or if type is not compatible
54 with the type of the actual next argument (as promoted according to the
55 default argument promotions), the behavior is undefined, except for the
56 following cases:
57 * One type is a signed integer type, the other type is the correspond‐
59 ing unsigned integer type, and the value is representable in both
60 types.
61 * One type is a pointer to void and the other is a pointer to a char‐
63 acter type.
64 * Both types are pointers.
66 Different types can be mixed, but it is up to the routine to know what
68 type of argument is expected.
69 The va_end() macro is used to clean up; it invalidates ap for use
71 (unless va_start() or va_copy() is invoked again).
72 Each invocation of the va_start() and va_copy() macros shall be matched
74 by a corresponding invocation of the va_end() macro in the same func‐
75 tion.
76 Multiple traversals, each bracketed by va_start() ... va_end(), are
78 possible.
79
81 This example is a possible implementation of execl():
82 #include <stdarg.h>
85 #define MAXARGS 31
88 /*
92 * execl is called by
93 * execl(file, arg1, arg2, ..., (char *)(0));
94 */
95 int execl(const char *file, const char *args, ...)
96 {
97 va_list ap;
98 char *array[MAXARGS +1];
99 int argno = 0;
100 va_start(ap, args);
103 while (args != 0 && argno < MAXARGS)
104 {
105 array[argno++] = args;
106 args = va_arg(ap, const char *);
107 }
108 array[argno] = (char *) 0;
109 va_end(ap);
110 return execv(file, array);
111 }
112 The following sections are informative.
114
116 It is up to the calling routine to communicate to the called routine
117 how many arguments there are, since it is not always possible for the
118 called routine to determine this in any other way. For example,
119 execl() is passed a null pointer to signal the end of the list. The
120 printf() function can tell how many arguments are there by the format
121 argument.
122
124 None.
125
127 None.
128
130 The System Interfaces volume of IEEE Std 1003.1-2001, exec, printf()
131
133 Portions of this text are reprinted and reproduced in electronic form
134 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
135 -- Portable Operating System Interface (POSIX), The Open Group Base
136 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
137 Electrical and Electronics Engineers, Inc and The Open Group. In the
138 event of any discrepancy between this version and the original IEEE and
139 The Open Group Standard, the original IEEE and The Open Group Standard
140 is the referee document. The original Standard can be obtained online
141 at http://www.opengroup.org/unix/online.html .
142IEEE/The Open Group 2003 <stdarg.h>(0P)