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

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   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 VARARGS 3EXT "May 10, 2002"
   7 .SH NAME
   8 varargs \- handle variable argument list
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <varargs.h>
  13 va_alist
  14 va_dcl
  15 va_list \fIpvar\fR;
  16
  17 \fBvoid\fR \fBva_start\fR(\fBva_list\fR\fIpvar\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBtype\fR \fBva_arg\fR(\fBva_list\fR \fIpvar\fR, \fB\fR\fItype\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBvoid\fR \fBva_end\fR(\fBva_list\fR \fIpvar\fR);
  28 .fi
  29
  30 .SH DESCRIPTION
  31 .sp
  32 .LP
  33 This set of macros allows portable procedures that accept variable argument
  34 lists to be written. Routines that have variable argument lists (such as
  35 \fBprintf\fR(3C)) but do not use \fBvarargs\fR are inherently non-portable, as
  36 different machines use different argument-passing conventions.
  37 .sp
  38 .LP
  39 \fBva_alist\fR is used as the parameter list in a function header.
  40 .sp
  41 .LP
  42 \fBva_dcl\fR is a declaration for \fBva_alist\fR. No semicolon should follow
  43 \fBva_dcl\fR.
  44 .sp
  45 .LP
  46 \fBva_list\fR is a type defined for the variable used to traverse the list.
  47 .sp
  48 .LP
  49 \fBva_start\fR is called to initialize \fBpvar\fR to the beginning of the list.
  50 .sp
  51 .LP
  52 \fBva_arg\fR will return the next argument in the list pointed to by
  53 \fBpvar\fR. \fBtype\fR is the type the argument is expected to be. Different
  54 types can be mixed, but it is up to the routine to know what type of argument
  55 is expected, as it cannot be determined at runtime.
  56 .sp
  57 .LP
  58 \fBva_end\fR is used to clean up.
  59 .sp
  60 .LP
  61 Multiple traversals, each bracketed by \fBva_start\fR and \fBva_end\fR, are
  62 possible.
  63 .SH EXAMPLES
  64 .LP
  65 \fBExample 1 \fRA sample program.
  66 .sp
  67 .LP
  68 This example is a possible implementation of \fBexecl\fR (see \fBexec\fR(2) ).
  69
  70 .sp
  71 .in +2
  72 .nf
  73 \fB#include <unistd.h>
  74 #include <varargs.h>
  75 #define MAXARGS 100
  76 /*      execl is called by
  77                 execl(file, arg1, arg2, ..., (char *)0);
  78 */
  79 execl(va_alist)
  80 va_dcl
  81 {
  82         va_list ap;
  83         char *file;
  84         char *args[MAXARGS];            /* assumed big enough*/
  85         int argno = 0;
  86
  87         va_start(ap);
  88         file = va_arg(ap, char *);
  89         while ((args[argno++] = va_arg(ap, char *)) != 0)
  90                 ;
  91         va_end(ap);
  92         return execv(file, args);
  93 }\fR
  94 .fi
  95 .in -2
  96 .sp
  97
  98 .SH SEE ALSO
  99 .sp
 100 .LP
 101 \fBexec\fR(2), \fBprintf\fR(3C), \fBvprintf\fR(3C), \fBstdarg\fR(3EXT)
 102 .SH NOTES
 103 .sp
 104 .LP
 105 It is up to the calling routine to specify in some manner how many arguments
 106 there are, since it is not always possible to determine the number of arguments
 107 from the stack frame. For example, \fBexecl\fR is passed a zero pointer to
 108 signal the end of the list. \fBprintf\fR can tell how many arguments are there
 109 by the format.
 110 .sp
 111 .LP
 112 It is non-portable to specify a second argument of \fBchar\fR, \fBshort\fR, or
 113 \fBfloat\fR to \fBva_arg\fR, since arguments seen by the called function are
 114 not \fBchar\fR, \fBshort\fR, or \fBfloat\fR. C converts \fBchar\fR and
 115 \fBshort\fR arguments to \fBint\fR and converts \fBfloat\fR arguments to
 116 \fBdouble\fR before passing them to a function.
 117 .sp
 118 .LP
 119 \fBstdarg\fR is the preferred interface.