Commit | Line | Data |
---|---|---|
41a44cfa KM |
1 | .\" @(#)stdarg.3 4.1 (Berkeley) %G% |
2 | .\" | |
3 | .TH VARARGS 3 | |
4 | .AT 3 | |
5 | .SH NAME | |
6 | varargs \- variable argument list | |
7 | .SH SYNOPSIS | |
8 | .nf | |
9 | #include <varargs.h> | |
10 | \fIfunction\fR(\fBva_alist\fR) | |
11 | \fBva_dcl | |
12 | va_list \fIpvar\fR; | |
13 | \fBva_start\fR(\fIpvar\fR); | |
14 | f = \fBva_arg\fR(\fIpvar\fR, \fItype\fR); | |
15 | \fBva_end\fR(\fIpvar\fR); | |
16 | .fi | |
17 | .SH DESCRIPTION | |
18 | This set of macros allows portable procedures that accept variable | |
19 | argument lists to be written. | |
20 | Routines which have variable argument lists (such as | |
21 | .IR printf(3)) | |
22 | that do not use varargs are inherently nonportable, since different | |
23 | machines use different argument passing conventions. | |
24 | .PP | |
25 | .B va_alist | |
26 | is used in a function header to declare a variable argument list. | |
27 | .PP | |
28 | .B va_dcl | |
29 | is a declaration for \fBva_alist\fP. | |
30 | Note that there is no semicolon after | |
31 | .B va_dcl. | |
32 | .PP | |
33 | .B va_list | |
34 | is a type which can be used for the variable | |
35 | .I pvar, | |
36 | which is used to traverse the list. | |
37 | One such variable must always be declared. | |
38 | .PP | |
39 | .B va_start | |
40 | .RI (pvar) | |
41 | is called to initialize | |
42 | .I pvar | |
43 | to the beginning of the list. | |
44 | .PP | |
45 | .B va_arg | |
46 | .RI ( pvar , type ) | |
47 | will return the next argument in the list | |
48 | pointed to by | |
49 | .IR pvar . | |
50 | .I Type | |
51 | is the type the argument is expected to be. | |
52 | Different types can be mixed, but it is up | |
53 | to the routine to know what type of argument is | |
54 | expected, since it cannot be determined at runtime. | |
55 | .PP | |
56 | .B va_end | |
57 | .RI ( pvar ) | |
58 | is used to finish up. | |
59 | .PP | |
60 | Multiple traversals, each bracketted by | |
61 | .B va_start | |
62 | \&.. | |
63 | .B va_end, | |
64 | are possible. | |
65 | .SH EXAMPLE | |
66 | .nf | |
67 | \fB#include\fP <varargs.h> | |
68 | execl(\fBva_alist\fP) | |
69 | \fBva_dcl\fP | |
70 | { | |
71 | \fBva_list\fP ap; | |
72 | \fBchar\fP *file; | |
73 | \fBchar\fP *args[100]; | |
74 | \fBint\fP argno = 0; | |
75 | ||
76 | \fBva_start\fP(ap); | |
77 | file = \fBva_arg(ap, \fBchar\fP *); | |
78 | \fBwhile\fP (args[argno++] = \fBva_arg\fP(ap, \fBchar\fP *)) | |
79 | \fB;\fP | |
80 | \fBva_end\fP(ap); | |
81 | \fBreturn\fP execv(file, args); | |
82 | } | |
83 | .fi | |
84 | .SH BUGS | |
85 | It is up to the calling routine to determine how many arguments | |
86 | there are, since it is not possible to determine this from the | |
87 | stack frame. For example, | |
88 | .I execl | |
89 | passes a 0 to signal the end of the list. | |
90 | .I Printf | |
91 | can tell how many arguments are there by the format. |