Return to varargs.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / man / man3

Annotation of 43BSDReno/share/man/man3/varargs.3, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1990 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted
        !             5: .\" provided that: (1) source distributions retain this entire copyright
        !             6: .\" notice and comment, and (2) distributions including binaries display
        !             7: .\" the following acknowledgement:  ``This product includes software
        !             8: .\" developed by the University of California, Berkeley and its contributors''
        !             9: .\" in the documentation or other materials provided with the distribution
        !            10: .\" and in all advertising materials mentioning features or use of this
        !            11: .\" software. Neither the name of the University nor the names of its
        !            12: .\" contributors may be used to endorse or promote products derived
        !            13: .\" from this software without specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
        !            15: .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
        !            16: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"    @(#)varargs.3   6.4 (Berkeley) 5/14/90
        !            19: .\"
        !            20: .TH VARARGS 3  "May 14, 1990"
        !            21: .AT 3
        !            22: .SH NAME
        !            23: varargs \- variable argument lists
        !            24: .SH SYNOPSIS
        !            25: .nf
        !            26: .ft B
        !            27: #include <stdarg.h>
        !            28: 
        !            29: void
        !            30: va_start(va_list ap, last);
        !            31: 
        !            32: type
        !            33: va_arg(va_list ap, type);
        !            34: 
        !            35: void
        !            36: va_end(va_list ap);
        !            37: .ft R
        !            38: .fi
        !            39: .SH DESCRIPTION
        !            40: A function may be called with a varying number of arguments of varying
        !            41: types.
        !            42: The include file
        !            43: .I <stdarg.h>
        !            44: declares a type (\fIva_list\fP) and defines three macros for stepping
        !            45: through a list of arguments whose number and types are not known to
        !            46: the called function.
        !            47: .PP
        !            48: The called function must declare an object of type
        !            49: .I va_list
        !            50: which is used by the macros
        !            51: .IR va_start ,
        !            52: .IR va_arg ,
        !            53: and
        !            54: .IR va_end .
        !            55: .PP
        !            56: The
        !            57: .I va_start
        !            58: macro initializes
        !            59: .I ap
        !            60: for subsequent use by
        !            61: .I va_arg
        !            62: and
        !            63: .IR va_end ,
        !            64: and must be called first.
        !            65: .PP
        !            66: The parameter
        !            67: .I last
        !            68: is the name of the last parameter before the variable argument list,
        !            69: i.e. the last parameter of which the calling function knows the type.
        !            70: .PP
        !            71: Because the address of this parameter is used in the
        !            72: .I va_start
        !            73: macro, it should not be declared as a register variable, or as a
        !            74: function or array type.
        !            75: .PP
        !            76: The
        !            77: .I va_start
        !            78: macro returns no value.
        !            79: .PP
        !            80: The
        !            81: .I va_arg
        !            82: macro expands to an expression that has the type and value of the next
        !            83: argument in the call.
        !            84: The parameter
        !            85: .I ap
        !            86: is the 
        !            87: .I va_list ap
        !            88: initialized by
        !            89: .IR va_start .
        !            90: Each call to 
        !            91: .I va_arg 
        !            92: modifies
        !            93: .I ap
        !            94: so that the next call returns the next argument.
        !            95: The parameter
        !            96: .I type
        !            97: is a type name specified so that the type of a pointer to an
        !            98: object that has the specified type can be obtained simply by 
        !            99: adding a 
        !           100: .I *
        !           101: to
        !           102: .IR type .
        !           103: .PP
        !           104: If there is no next argument, or if
        !           105: .I type
        !           106: is not compatible with the type of the actual next argument
        !           107: (as promoted according to the default argument promotions),
        !           108: random errors will occur.
        !           109: .PP
        !           110: The first use of the
        !           111: .I va_arg
        !           112: macro after that of the 
        !           113: .I va_start 
        !           114: macro returns the argument after 
        !           115: .IR last .
        !           116: Successive invocations return the values of the remaining
        !           117: arguments.
        !           118: .PP
        !           119: The
        !           120: .I va_end
        !           121: macro handles a normal return from the function whose variable argument
        !           122: list was initialized by 
        !           123: .IR va_start .
        !           124: .PP
        !           125: The
        !           126: .I va_end
        !           127: macro returns no value.
        !           128: .SH STANDARDS
        !           129: The
        !           130: .IR va_start ,
        !           131: .IR va_arg ,
        !           132: and
        !           133: .I va_end
        !           134: macros are ANSI C compatible.
        !           135: .SH COMPATIBILITY
        !           136: These macros are
        !           137: .B not
        !           138: compatible with the historic macros they replace.
        !           139: A backward compatible version can be found in the include
        !           140: file 
        !           141: .IR <varargs.h> .
        !           142: .SH EXAMPLES
        !           143: The function
        !           144: .I foo
        !           145: takes a string of format characters and prints out the argument
        !           146: associated with each format character based on the type.
        !           147: .sp
        !           148: .nf
        !           149: .RS
        !           150: foo(fmt)
        !           151:        char *fmt;
        !           152: {
        !           153:        va_list ap;
        !           154:        int d;
        !           155:        char c, *p, *s;
        !           156: 
        !           157:        va_start(ap, fmt);
        !           158:        while (*fmt)
        !           159:                switch(*fmt++) {
        !           160:                case 's':                       /* string */
        !           161:                        s = va_arg(ap, char *);
        !           162:                        printf("string %s\en", s);
        !           163:                        break;
        !           164:                case 'd':                       /* int */
        !           165:                        d = va_arg(ap, int);
        !           166:                        printf("int %d\en", d);
        !           167:                        break;
        !           168:                case 'c':                       /* char */
        !           169:                        c = va_arg(ap, char);
        !           170:                        printf("char %c\en", c);
        !           171:                        break;
        !           172:                }
        !           173:        va_end(ap);
        !           174: }
        !           175: .fi

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