1STDARG(3)                  Linux Programmer's Manual                 STDARG(3)
2
3
4

NAME

6       stdarg, va_start, va_arg, va_end, va_copy - variable argument lists
7

SYNOPSIS

9       #include <stdarg.h>
10
11       void va_start(va_list ap, last);
12       type va_arg(va_list ap, type);
13       void va_end(va_list ap);
14       void va_copy(va_list dest, va_list src);
15

DESCRIPTION

17       A  function may be called with a varying number of arguments of varying
18       types.  The include file <stdarg.h> declares a type va_list and defines
19       three  macros for stepping through a list of arguments whose number and
20       types are not known to the called function.
21
22       The called function must declare an object of  type  va_list  which  is
23       used by the macros va_start(), va_arg(), and va_end().
24
25   va_start()
26       The  va_start() macro initializes ap for subsequent use by va_arg() and
27       va_end(), and must be called first.
28
29       The argument last is the name of the last argument before the  variable
30       argument list, that is, the last argument of which the calling function
31       knows the type.
32
33       Because the address of this argument may  be  used  in  the  va_start()
34       macro,  it should not be declared as a register variable, or as a func‐
35       tion or an array type.
36
37   va_arg()
38       The va_arg() macro expands to an expression that has the type and value
39       of  the  next  argument in the call.  The argument ap is the va_list ap
40       initialized by va_start().  Each call to va_arg() modifies ap  so  that
41       the  next  call returns the next argument.  The argument type is a type
42       name specified so that the type of a pointer to an object that has  the
43       specified type can be obtained simply by adding a * to type.
44
45       The  first use of the va_arg() macro after that of the va_start() macro
46       returns the argument after last.   Successive  invocations  return  the
47       values of the remaining arguments.
48
49       If  there  is  no  next argument, or if type is not compatible with the
50       type of the actual next argument (as promoted according to the  default
51       argument promotions), random errors will occur.
52
53       If  ap is passed to a function that uses va_arg(ap,type) then the value
54       of ap is undefined after the return of that function.
55
56   va_end()
57       Each invocation of va_start() must be matched by a corresponding  invo‐
58       cation of va_end() in the same function.  After the call va_end(ap) the
59       variable ap is undefined.  Multiple traversals of the list, each brack‐
60       eted  by va_start() and va_end() are possible.  va_end() may be a macro
61       or a function.
62
63   va_copy()
64       An obvious implementation would have a va_list  be  a  pointer  to  the
65       stack frame of the variadic function.  In such a setup (by far the most
66       common) there seems nothing against an assignment
67
68           va_list aq = ap;
69
70       Unfortunately, there are also systems that make it an array of pointers
71       (of length 1), and there one needs
72
73           va_list aq;
74           *aq = *ap;
75
76       Finally,  on systems where arguments are passed in registers, it may be
77       necessary for va_start() to allocate memory, store the arguments there,
78       and  also an indication of which argument is next, so that va_arg() can
79       step through the list.  Now va_end()  can  free  the  allocated  memory
80       again.   To  accommodate this situation, C99 adds a macro va_copy(), so
81       that the above assignment can be replaced by
82
83           va_list aq;
84           va_copy(aq, ap);
85           ...
86           va_end(aq);
87
88       Each invocation of va_copy() must be matched by a corresponding invoca‐
89       tion of va_end() in the same function.  Some systems that do not supply
90       va_copy() have __va_copy instead, since that was the name used  in  the
91       draft proposal.
92

CONFORMING TO

94       The  va_start(),  va_arg(),  and  va_end()  macros conform to C89.  C99
95       defines the va_copy() macro.
96

NOTES

98       These macros are not compatible with the historic macros they  replace.
99       A  backward  compatible  version  can  be  found  in  the  include file
100       <varargs.h>.
101
102       The historic setup is:
103
104           #include <varargs.h>
105
106           void
107           foo(va_alist)
108               va_dcl
109           {
110               va_list ap;
111
112               va_start(ap);
113               while (...) {
114                   ...
115                   x = va_arg(ap, type);
116                   ...
117               }
118               va_end(ap);
119           }
120
121       On some systems, va_end contains  a  closing  '}'  matching  a  '{'  in
122       va_start, so that both macros must occur in the same function, and in a
123       way that allows this.
124

BUGS

126       Unlike the varargs macros, the stdarg macros do not permit  programmers
127       to  code  a  function  with no fixed arguments.  This problem generates
128       work mainly when converting varargs code to stdarg code,  but  it  also
129       creates  difficulties  for  variadic functions that wish to pass all of
130       their arguments on to a function that takes a va_list argument, such as
131       vfprintf(3).
132

EXAMPLE

134       The function foo takes a string of format characters and prints out the
135       argument associated with each format character based on the type.
136
137       #include <stdio.h>
138       #include <stdarg.h>
139
140       void
141       foo(char *fmt, ...)
142       {
143           va_list ap;
144           int d;
145           char c, *s;
146
147           va_start(ap, fmt);
148           while (*fmt)
149               switch (*fmt++) {
150               case 's':              /* string */
151                   s = va_arg(ap, char *);
152                   printf("string %s\n", s);
153                   break;
154               case 'd':              /* int */
155                   d = va_arg(ap, int);
156                   printf("int %d\n", d);
157                   break;
158               case 'c':              /* char */
159                   /* need a cast here since va_arg only
160                      takes fully promoted types */
161                   c = (char) va_arg(ap, int);
162                   printf("char %c\n", c);
163                   break;
164               }
165           va_end(ap);
166       }
167

COLOPHON

169       This page is part of release 3.25 of the Linux  man-pages  project.   A
170       description  of  the project, and information about reporting bugs, can
171       be found at http://www.kernel.org/doc/man-pages/.
172
173
174
175                                  2001-10-14                         STDARG(3)
Impressum