usr/src/man/man3ext/stdarg.3ext

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 2006, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH STDARG 3EXT "Mar 22, 2006"
   7 .SH NAME
   8 stdarg \- handle variable argument list
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <stdarg.h>
  13 va_list \fIpvar\fR;
  14
  15 \fBvoid\fR \fBva_start\fR(\fBva_list\fR \fIpvar\fR, \fBvoid\fR \fIname\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fB(type *)\fR \fBva_arg\fR(\fBva_list\fR \fIpvar\fR, \fB\fR\fItype\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBvoid\fR \fBva_copy\fR(\fBva_list\fR \fIdest\fR, \fBva_list\fR \fIsrc\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBvoid\fR \fBva_end\fR(\fBva_list\fR \fIpvar\fR);
  31 .fi
  32
  33 .SH DESCRIPTION
  34 .sp
  35 .LP
  36 This set of macros allows portable procedures that accept variable numbers of
  37 arguments of variable types to be written. Routines that have variable argument
  38 lists (such as \fBprintf\fR) but do not use \fIstdarg\fR are inherently
  39 non-portable, as different machines use different argument-passing conventions.
  40 .sp
  41 .LP
  42 \fBva_list\fR is a type defined for the variable used to traverse the list.
  43 .sp
  44 .LP
  45 The \fBva_start\fR macro is invoked before any access to the unnamed arguments
  46 and initializes \fIpvar\fR for subsequent use by \fBva_arg()\fR and
  47 \fBva_end()\fR. The parameter \fIname\fR is the identifier of the rightmost
  48 parameter in the variable parameter list in the function definition (the one
  49 just before the \fB, ...\fR). If this parameter is declared with the
  50 \fBregister\fR storage class or with a function or array type, or with a type
  51 that is not compatible with the type that results after application of the
  52 default argument promotions, the behavior is undefined.
  53 .sp
  54 .LP
  55 The parameter \fIname\fR is required under strict ANSI C compilation. In other
  56 compilation modes, \fIname\fR need not be supplied and the second parameter to
  57 the \fBva_start()\fR macro can be left empty (for example, \fBva_start(pvar,
  58 );\fR). This allows for routines that contain no parameters before the
  59 \fB\&...\fR in the variable parameter list.
  60 .sp
  61 .LP
  62 The \fBva_arg()\fR macro expands to an expression that has the type and value
  63 of the next argument in the call. The parameter \fBpvar\fR should have been
  64 previously initialized by \fBva_start()\fR. Each invocation of \fBva_arg()\fR
  65 modifies \fBpvar\fR so that the values of successive arguments are returned in
  66 turn. The parameter \fBtype\fR is the type name of the next argument to be
  67 returned. The type name must be specified in such a way so that the type of a
  68 pointer to an object that has the specified type can be obtained simply by
  69 postfixing a \fB*\fR to \fItype\fR. If there is no actual next argument, or if
  70 \fItype\fR is not compatible with the type of the actual next argument (as
  71 promoted according to the default argument promotions), the behavior is
  72 undefined.
  73 .sp
  74 .LP
  75 The \fBva_copy()\fR macro saves the state represented by the
  76 \fBva_list\fR\fIsrc\fR in the \fBva_list\fR \fIdest\fR. The \fBva_list\fR
  77 passed as \fIdest\fR should not be initialized by a previous call to
  78 \fBva_start()\fR, and must be passed to \fBva_end()\fR before being reused as a
  79 parameter to \fBva_start()\fR or as the \fIdest\fR parameter of a subsequent
  80 call to \fBva_copy()\fR. The behavior is undefined should any of these
  81 restrictions not be met.
  82 .sp
  83 .LP
  84 The \fBva_end()\fR macro is used to clean up.
  85 .sp
  86 .LP
  87 Multiple traversals, each bracketed by \fBva_start()\fR and \fBva_end()\fR, are
  88 possible.
  89 .SH EXAMPLES
  90 .LP
  91 \fBExample 1 \fRA sample program.
  92 .sp
  93 .LP
  94 This example gathers into an array a list of arguments that are pointers to
  95 strings (but not more than \fBMAXARGS\fR arguments) with function \fBf1\fR,
  96 then passes the array as a single argument to function \fBf2\fR. The number of
  97 pointers is specified by the first argument to \fBf1\fR.
  98
  99 .sp
 100 .in +2
 101 .nf
 102 #include <stdarg.h>
 103 #define MAXARGS 31
 104 void f1(int n_ptrs, ...)
 105 {
 106      va_list ap;
 107      char *array[MAXARGS];
 108      int ptr_no = 0;
 109
 110      if (n_ptrs > MAXARGS)
 111           n_ptrs = MAXARGS;
 112      va_start(ap, n_ptrs);
 113      while (ptr_no < n_ptrs)
 114           array[ptr_no++] = va_arg(ap, char*);
 115      va_end(ap);
 116      f2(n_ptrs, array);
 117 }
 118 .fi
 119 .in -2
 120
 121 .sp
 122 .LP
 123 Each call to \fBf1\fR shall have visible the definition of the function or a
 124 declaration such as
 125
 126 .sp
 127 .in +2
 128 .nf
 129 \fBvoid f1(int, ...)\fR
 130 .fi
 131 .in -2
 132 .sp
 133
 134 .SH ATTRIBUTES
 135 .sp
 136 .LP
 137 See \fBattributes\fR(5) for descriptions of the following attributes:
 138 .sp
 139
 140 .sp
 141 .TS
 142 box;
 143 c | c
 144 l | l .
 145 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 146 _
 147 Interface Stability     Standard
 148 .TE
 149
 150 .SH SEE ALSO
 151 .sp
 152 .LP
 153 \fBvprintf\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
 154 .SH NOTES
 155 .sp
 156 .LP
 157 It is the responsibility of the calling routine to specify in some manner how
 158 many arguments there are, since it is not always possible to determine the
 159 number of arguments from the stack frame. For example, \fIexecl\fR is passed a
 160 zero pointer to signal the end of the list. The \fIprintf\fR function can
 161 determine the number of arguments by the format. It is non-portable to specify
 162 a second argument of \fBchar\fR, \fBshort\fR, or \fBfloat\fR to \fBva_arg()\fR,
 163 because arguments seen by the called function are not \fBchar\fR, \fBshort\fR,
 164 or \fBfloat\fR. C converts \fBchar\fR and \fBshort\fR arguments to \fBint\fR
 165 and converts \fBfloat\fR arguments to \fBdouble\fR before passing them to a
 166 function.