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     ! 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.