usr/src/man/man9f/va_arg.9f

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc.,  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH VA_ARG 9F "Mar 21, 2017"
   8 .SH NAME
   9 va_arg, va_start, va_copy, va_end \- handle variable argument list
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/varargs.h>
  14
  15
  16
  17 \fBvoid\fR \fBva_start\fR(\fBva_list\fR \fIpvar\fR, \fB\fR\fIname\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fB(type *)\fR \fBva_arg\fR(\fBva_list\fR \fIpvar\fR, \fB\fR\fItype\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBvoid\fR \fBva_copy\fR(\fBva_list\fR \fIdest\fR, \fBva_list\fR \fIsrc\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBvoid\fR \fBva_end\fR(\fBva_list\fR \fIpvar\fR);
  33 .fi
  34
  35 .SH INTERFACE LEVEL
  36 .LP
  37 Solaris DDI specific (Solaris DDI).
  38 .SH PARAMETERS
  39 .SS "\fBva_start()\fR"
  40 .ne 2
  41 .na
  42 \fB\fIpvar\fR\fR
  43 .ad
  44 .RS 8n
  45 Pointer to variable argument list.
  46 .RE
  47
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fIname\fR\fR
  52 .ad
  53 .RS 8n
  54 Identifier of rightmost parameter in the function definition.
  55 .RE
  56
  57 .SS "\fBva_arg()\fR"
  58 .ne 2
  59 .na
  60 \fB\fIpvar\fR\fR
  61 .ad
  62 .RS 8n
  63 Pointer to variable argument list.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fItype\fR\fR
  70 .ad
  71 .RS 8n
  72 Type name of the next argument to be returned.
  73 .RE
  74
  75 .SS "\fBva_copy()\fR"
  76 .ne 2
  77 .na
  78 \fB\fIdest\fR\fR
  79 .ad
  80 .RS 8n
  81 Destination variable argument list.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fIsrc\fR\fR
  88 .ad
  89 .RS 8n
  90 Source variable argument list.
  91 .RE
  92
  93 .SS "\fBva_end()\fR"
  94 .ne 2
  95 .na
  96 \fB\fIpvar\fR\fR
  97 .ad
  98 .RS 8n
  99 Pointer to variable argument list.
 100 .RE
 101
 102 .SH DESCRIPTION
 103 .LP
 104 This set of macros allows portable procedures that accept variable argument
 105 lists to be written. Routines that have variable argument lists but do not use
 106 the \fBvarargs\fR macros are inherently non-portable, as different machines use
 107 different argument-passing conventions. Routines that accept a variable
 108 argument list can use these macros to traverse the list.
 109 .sp
 110 .LP
 111 \fBva_list\fR is the type defined for the variable used to traverse the list of
 112 arguments.
 113 .sp
 114 .LP
 115 \fBva_start()\fR is called to initialize \fIpvar\fR to the beginning of the
 116 variable argument list. \fBva_start()\fR must be invoked before any access to
 117 the unnamed arguments. The parameter \fIname\fR is the identifier of the
 118 rightmost parameter in the variable parameter list in the function definition
 119 (the one just before the "\fB, .\|.\|.\|\fR"). If this parameter is declared
 120 with the \fBregister\fR storage class or with a function or array type, or with
 121 a type that is not compatible with the type that results after application of
 122 the default argument promotions, the behavior is undefined.
 123 .sp
 124 .LP
 125 \fBva_arg()\fR expands to an expression that has the type and value of the next
 126 argument in the call. The parameter \fIpvar\fR must be initialized by
 127 \fBva_start()\fR. Each invocation of \fBva_arg()\fR modifies \fIpvar\fR so that
 128 the values of successive arguments are returned in turn. The parameter
 129 \fItype\fR is the type name of the next argument to be returned. The type name
 130 must be specified in such a way that the type of pointer to an object that has
 131 the specified type can be obtained by postfixing a \fB*\fR to \fItype\fR. If
 132 there is no actual next argument, or if \fBtype\fR is not compatible with the
 133 type of the actual next argument (as promoted according to the default argument
 134 promotions), the behavior is undefined.
 135 .sp
 136 .LP
 137 The \fBva_copy()\fR macro saves the state represented by the
 138 \fBva_list\fR \fIsrc\fR in the \fBva_list\fR \fIdest\fR. The \fBva_list\fR
 139 passed as \fIdest\fR should not be initialized by a previous call to
 140 \fBva_start()\fR. It then must be passed to \fBva_end()\fR before being reused
 141 as a parameter to \fBva_start()\fR or as the \fIdest\fR parameter of a
 142 subsequent call to \fBva_copy()\fR. The behavior is undefined if any of these
 143 restrictions are not met.
 144 .sp
 145 .LP
 146 The \fBva_end()\fR macro is used to clean up. It invalidates \fIpvar\fR for use
 147 (unless \fBva_start()\fR is invoked again).
 148 .sp
 149 .LP
 150 Multiple traversals, each bracketed by a call to \fBva_start()\fR and
 151 \fBva_end()\fR, are possible.
 152 .SH EXAMPLES
 153 .LP
 154 \fBExample 1 \fRCreating a Variable Length Command
 155 .sp
 156 .LP
 157 The following example uses these routines to create a variable length command.
 158 This might be useful for a device that provides for a variable-length command
 159 set. \fBncmdbytes\fR is the number of bytes in the command. The new command is
 160 written to \fBcmdp\fR.
 161
 162 .sp
 163 .in +2
 164 .nf
 165 static void
 166 xx_write_cmd(uchar_t *cmdp, int ncmdbytes, ...)
 167 {
 168         va_list ap;
 169         int     i;
 170
 171         /*
 172          * Write variable-length command to destination
 173          */
 174         va_start(ap, ncmdbytes);
 175         for (i = 0; i < ncmdbytes; i++) {
 176                 *cmdp++ = va_arg(ap, uchar_t);
 177         }
 178         va_end(ap);
 179 }
 180 .fi
 181 .in -2
 182
 183 .SH SEE ALSO
 184 .LP
 185 \fBvcmn_err\fR(9F), \fBvsprintf\fR(9F)
 186 .SH NOTES
 187 .LP
 188 It is up to the calling routine to specify in some manner how many arguments
 189 there are, since it is not always possible to determine the number of arguments
 190 from the stack frame.
 191 .sp
 192 .LP
 193 Specifying a second argument of \fBchar\fR or \fBshort\fR to \fBva_arg\fR makes
 194 your code non-portable, because arguments seen by the called function are not
 195 \fBchar\fR or \fBshort\fR. C converts \fBchar\fR and \fBshort\fR arguments to
 196 \fBint\fR before passing them to a function.