Return to varargs.3 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man3

Annotation of 43BSDTahoe/man/man3/varargs.3, revision 1.1.1.1

1.1       root        1: .\"    @(#)varargs.3   6.3 (Berkeley) 5/15/86
                      2: .\"
                      3: .TH VARARGS 3  "May 15, 1986"
                      4: .AT 3
                      5: .SH NAME
                      6: varargs \- variable argument list
                      7: .SH SYNOPSIS
                      8: .B "#include <varargs.h>"
                      9: .PP
                     10: .I function\c
                     11: .RB ( va_alist )
                     12: .br
                     13: .B va_dcl
                     14: .br
                     15: .B va_list
                     16: .IR pvar ;
                     17: .br
                     18: .B va_start\c
                     19: .RI ( pvar );
                     20: .br
                     21: f =
                     22: .B va_arg\c
                     23: .RI ( pvar ,
                     24: .IR type );
                     25: .br
                     26: .B va_end\c
                     27: .RI ( pvar );
                     28: .SH DESCRIPTION
                     29: This set of macros provides a means of writing portable procedures that
                     30: accept variable argument lists.
                     31: Routines having variable argument lists (such as
                     32: .IR printf (3))
                     33: that do not use varargs are inherently nonportable, since different
                     34: machines use different argument passing conventions.
                     35: .PP
                     36: .B va_alist
                     37: is used in a function header to declare a variable argument list.
                     38: .PP
                     39: .B va_dcl
                     40: is a declaration for
                     41: .BR va_alist .
                     42: Note that there is no semicolon after
                     43: .B va_dcl.
                     44: .PP
                     45: .B va_list
                     46: is a type which can be used for the variable
                     47: .IR pvar ,
                     48: which is used to traverse the list.
                     49: One such variable must always be declared.
                     50: .PP
                     51: .B va_start\c
                     52: .RI (pvar)
                     53: is called to initialize
                     54: .I pvar
                     55: to the beginning of the list.
                     56: .PP
                     57: .B va_arg\c
                     58: .RI ( pvar ,
                     59: .IR type )
                     60: will return the next argument in the list pointed to by
                     61: .IR pvar .
                     62: .I Type
                     63: is the type to which the expected argument will be converted
                     64: when passed as an argument.
                     65: In standard C, arguments that are
                     66: .B char
                     67: or
                     68: .B short
                     69: should be accessed as
                     70: .BR int ,
                     71: .B "unsigned char
                     72: or
                     73: .B "unsigned short
                     74: are converted to
                     75: .BR "unsigned int" ,
                     76: and
                     77: .B float
                     78: arguments are converted to
                     79: .BR double .
                     80: Different types can be mixed, but it is up
                     81: to the routine to know what type of argument is
                     82: expected, since it cannot be determined at runtime.
                     83: .PP
                     84: .B va_end\c
                     85: .RI ( pvar )
                     86: is used to finish up.
                     87: .PP
                     88: Multiple traversals, each bracketed by
                     89: .B va_start
                     90: \&...
                     91: .B va_end,
                     92: are possible.
                     93: .SH EXAMPLE
                     94: .nf
                     95:        \fB#include\fP <varargs.h>
                     96:        execl(\fBva_alist\fP)
                     97:        \fBva_dcl\fP
                     98:        {
                     99:                \fBva_list\fP ap;
                    100:                \fBchar\fP *file;
                    101:                \fBchar\fP *args[100];
                    102:                \fBint\fP argno = 0;
                    103: 
                    104:                \fBva_start\fP(ap);
                    105:                file = \fBva_arg(ap, \fBchar\fP *);
                    106:                \fBwhile\fP (args[argno++] = \fBva_arg\fP(ap, \fBchar\fP *))
                    107:                        \fB;\fP
                    108:                \fBva_end\fP(ap);
                    109:                \fBreturn\fP execv(file, args);
                    110:        }
                    111: .fi
                    112: .SH BUGS
                    113: It is up to the calling routine to determine how many arguments
                    114: there are, since it is not possible to determine this from the
                    115: stack frame.  For example,
                    116: .I execl
                    117: passes a 0 to signal the end of the list.
                    118: .I Printf
                    119: can tell how many arguments are supposed to be there by the format.
                    120: .PP
                    121: The macros
                    122: .I va_start
                    123: and
                    124: .I va_end
                    125: may be arbitrarily complex;
                    126: for example,
                    127: .I va_start
                    128: might contain an opening brace,
                    129: which is closed by a matching brace in
                    130: .IR va_end .
                    131: Thus, they should only be used where they could
                    132: be placed within a single complex statement.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.