man/man3/stdarg.3

   1 .\"     @(#)varargs.3   6.3 (Berkeley) 5/15/86
   2 .\"
   3 .TH STDARG 3  "May 15, 1986"
   4 .AT 3
   5 .SH NAME
   6 stdarg \- variable argument list
   7 .SH SYNOPSIS
   8 .nf
   9 .ft B
  10 #include <stdarg.h>
  11
  12 void va_start(va_list \fIap\fP, \fIargtypeN\fP \fIparmN\fP)
  13 \fItype\fP va_arg(va_list \fIap\fP, \fItype\fP)
  14 void va_end(va_list \fIap\fP)
  15 .ft R
  16 .fi
  17 .SH DESCRIPTION
  18 This set of macros provides a means of writing portable procedures that
  19 accept variable argument lists.
  20 Routines having variable argument lists (such as
  21 .BR printf (3))
  22 that do not use
  23 .B stdarg
  24 are inherently nonportable, since different
  25 machines use different argument passing conventions.
  26 .PP
  27 A function that accepts a variable argument list is declared with "..." at
  28 the end of its parameter list.  It must have at least one normal argument
  29 before the "...".  For example:
  30 .PP
  31 .RS
  32 .nf
  33 int printf(const char *format, ...) { /* code */ }
  34 int fprintf(FILE *stream, const char *format, ...) { /* code */ }
  35 .fi
  36 .RE
  37 .PP
  38 .B va_list
  39 is a type which is used for the variable
  40 .I ap
  41 within the body of a variable argument function which is used to traverse
  42 the list.
  43 .PP
  44 .B va_start\c
  45 .RI ( ap ,
  46 .IR parmN )
  47 is called to initialize
  48 .I ap
  49 to the beginning of the list.  The last true parameter of the function,
  50 .IR parmN ,
  51 must be supplied to allow
  52 .B va_start
  53 to compute the address of the first variable parameter.
  54 .PP
  55 .B va_arg\c
  56 .RI ( ap ,
  57 .IR type )
  58 will return the next argument in the list pointed to by
  59 .IR ap .
  60 .I Type
  61 is the type to which the expected argument will be converted
  62 when passed as an argument.
  63 .PP
  64 Different types can be mixed, but it is up
  65 to the routine to know what type of argument is
  66 expected, since it cannot be determined at runtime.
  67 .PP
  68 .B va_end\c
  69 .RI ( ap )
  70 must be used to finish up.
  71 .PP
  72 Multiple traversals, each bracketed by
  73 .B va_start
  74 \&...
  75 .B va_end,
  76 are possible.
  77 .SH EXAMPLE
  78 .nf
  79 .ta +4n +4n +4n +4n
  80         \fB#include\fP <stdarg.h>
  81 .sp 0.4
  82         execl(\fBconst char\fP *path, \fB...\fP)
  83         {
  84                 \fBva_list\fP ap;
  85                 \fBchar\fP *args[100];
  86                 \fBint\fP argno = 0;
  87
  88                 \fBva_start\fP(ap, path);
  89                 \fBwhile\fP ((args[argno++] = \fBva_arg\fP(ap, \fBchar\fP *)) != NULL) {}
  90                 \fBva_end\fP(ap);
  91                 \fBreturn\fP execv(path, args);
  92         }
  93 .DT
  94 .fi
  95 .SH NOTES
  96 It is up to the calling routine to determine how many arguments
  97 there are, since it is not possible to determine this from the
  98 stack frame.  For example,
  99 .B execl
 100 passes a null pointer to signal the end of the list.
 101 .B Printf
 102 can tell how many arguments are supposed to be there by the format.
 103 .PP
 104 The macros
 105 .B va_start
 106 and
 107 .B va_end
 108 may be arbitrarily complex;
 109 for example,
 110 .B va_start
 111 might contain an opening brace,
 112 which is closed by a matching brace in
 113 .BR va_end .
 114 Thus, they should only be used where they could
 115 be placed within a single complex statement.
 116 .SH BUGS
 117 It is impossible to properly show the macros as C declarations as is
 118 done in the synopsis.  They can never be coded as C functions, because
 119 all three macros use their arguments by address, and the
 120 .I type
 121 field is certainly impossible.
 122 Just look at them as being part of the C language, like
 123 .BR sizeof .