1stdarg.h(0P) POSIX Programmer's Manual stdarg.h(0P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 stdarg.h — handle variable argument list
14
16 #include <stdarg.h>
17 void va_start(va_list ap, argN);
19 void va_copy(va_list dest, va_list src);
20 type va_arg(va_list ap, type);
21 void va_end(va_list ap);
22
24 The functionality described on this reference page is aligned with the
25 ISO C standard. Any conflict between the requirements described here
26 and the ISO C standard is unintentional. This volume of POSIX.1‐2008
27 defers to the ISO C standard.
28 The <stdarg.h> header shall contain a set of macros which allows porta‐
30 ble functions that accept variable argument lists to be written. Func‐
31 tions that have variable argument lists (such as printf()) but do not
32 use these macros are inherently non-portable, as different systems use
33 different argument-passing conventions.
34 The <stdarg.h> header shall define the va_list type for variables used
36 to traverse the list.
37 The va_start() macro is invoked to initialize ap to the beginning of
39 the list before any calls to va_arg().
40 The va_copy() macro initializes dest as a copy of src, as if the
42 va_start() macro had been applied to dest followed by the same sequence
43 of uses of the va_arg() macro as had previously been used to reach the
44 present state of src. Neither the va_copy() nor va_start() macro shall
45 be invoked to reinitialize dest without an intervening invocation of
46 the va_end() macro for the same dest.
47 The object ap may be passed as an argument to another function; if that
49 function invokes the va_arg() macro with parameter ap, the value of ap
50 in the calling function is unspecified and shall be passed to the
51 va_end() macro prior to any further reference to ap. The parameter
52 argN is the identifier of the rightmost parameter in the variable
53 parameter list in the function definition (the one just before the
54 ...). If the parameter argN is declared with the register storage
55 class, with a function type or array type, or with a type that is not
56 compatible with the type that results after application of the default
57 argument promotions, the behavior is undefined.
58 The va_arg() macro shall return the next argument in the list pointed
60 to by ap. Each invocation of va_arg() modifies ap so that the values
61 of successive arguments are returned in turn. The type parameter shall
62 be a type name specified such that the type of a pointer to an object
63 that has the specified type can be obtained simply by postfixing a '*'
64 to type. If there is no actual next argument, or if type is not compat‐
65 ible with the type of the actual next argument (as promoted according
66 to the default argument promotions), the behavior is undefined, except
67 for the following cases:
68 * One type is a signed integer type, the other type is the corre‐
70 sponding unsigned integer type, and the value is representable in
71 both types.
72 * One type is a pointer to void and the other is a pointer to a char‐
74 acter type.
75 * Both types are pointers.
77 Different types can be mixed, but it is up to the routine to know what
79 type of argument is expected.
80 The va_end() macro is used to clean up; it invalidates ap for use
82 (unless va_start() or va_copy() is invoked again).
83 Each invocation of the va_start() and va_copy() macros shall be matched
85 by a corresponding invocation of the va_end() macro in the same func‐
86 tion.
87 Multiple traversals, each bracketed by va_start() ... va_end(), are
89 possible.
90 The following sections are informative.
92
94 This example is a possible implementation of execl():
95 #include <stdarg.h>
97 #define MAXARGS 31
99 /*
101 * execl is called by
102 * execl(file, arg1, arg2, ..., (char *)(0));
103 */
104 int execl(const char *file, const char *args, ...)
105 {
106 va_list ap;
107 char *array[MAXARGS +1];
108 int argno = 0;
109 va_start(ap, args);
111 while (args != 0 && argno < MAXARGS)
112 {
113 array[argno++] = args;
114 args = va_arg(ap, const char *);
115 }
116 array[argno] = (char *) 0;
117 va_end(ap);
118 return execv(file, array);
119 }
120
122 It is up to the calling routine to communicate to the called routine
123 how many arguments there are, since it is not always possible for the
124 called routine to determine this in any other way. For example, execl()
125 is passed a null pointer to signal the end of the list. The printf()
126 function can tell how many arguments are there by the format argument.
127
129 None.
130
132 None.
133
135 The System Interfaces volume of POSIX.1‐2008, exec, fprintf()
136
138 Portions of this text are reprinted and reproduced in electronic form
139 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
140 -- Portable Operating System Interface (POSIX), The Open Group Base
141 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
142 cal and Electronics Engineers, Inc and The Open Group. (This is
143 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
144 event of any discrepancy between this version and the original IEEE and
145 The Open Group Standard, the original IEEE and The Open Group Standard
146 is the referee document. The original Standard can be obtained online
147 at http://www.unix.org/online.html .
148 Any typographical or formatting errors that appear in this page are
150 most likely to have been introduced during the conversion of the source
151 files to man page format. To report such errors, see https://www.ker‐
152 nel.org/doc/man-pages/reporting_bugs.html .
153IEEE/The Open Group 2013 stdarg.h(0P)