diff options
Diffstat (limited to 'man/man3/stdarg.3')
| -rw-r--r-- | man/man3/stdarg.3 | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/man/man3/stdarg.3 b/man/man3/stdarg.3 new file mode 100644 index 000000000..4168487d0 --- /dev/null +++ b/man/man3/stdarg.3 @@ -0,0 +1,297 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)stdarg.3 6.8 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:11:11 1993, faith@cs.unc.edu +.\" Additions, 2001-10-14, aeb +.\" +.TH stdarg 3 (date) "Linux man-pages (unreleased)" +.SH NAME +stdarg, va_start, va_arg, va_end, va_copy \- variable argument lists +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdarg.h> +.P +.BI "void va_start(va_list " ap ", " last ); +.IB type " va_arg(va_list " ap ", " type ); +.BI "void va_end(va_list " ap ); +.BI "void va_copy(va_list " dest ", va_list " src ); +.fi +.SH DESCRIPTION +A function may be called with a varying number of arguments of varying +types. +The include file +.I <stdarg.h> +declares a type +.I va_list +and defines three macros for stepping through a list of arguments whose +number and types are not known to the called function. +.P +The called function must declare an object of type +.I va_list +which is used by the macros +.BR va_start (), +.BR va_arg (), +and +.BR va_end (). +.SS va_start() +The +.BR va_start () +macro initializes +.I ap +for subsequent use by +.BR va_arg () +and +.BR va_end (), +and must be called first. +.P +The argument +.I last +is the name of the last argument before the variable argument list, that is, +the last argument of which the calling function knows the type. +.P +Because the address of this argument may be used in the +.BR va_start () +macro, it should not be declared as a register variable, +or as a function or an array type. +.SS va_arg() +The +.BR va_arg () +macro expands to an expression that has the type and value of the next +argument in the call. +The argument +.I ap +is the +.I va_list +.I ap +initialized by +.BR va_start (). +Each call to +.BR va_arg () +modifies +.I ap +so that the next call returns the next argument. +The argument +.I type +is a type name specified so that the type of a pointer to an object that +has the specified type can be obtained simply by adding a * to +.IR type . +.P +The first use of the +.BR va_arg () +macro after that of the +.BR va_start () +macro returns the argument after +.IR last . +Successive invocations return the values of the remaining arguments. +.P +If there is no next argument, or if +.I type +is not compatible with the type of the actual next argument (as promoted +according to the default argument promotions), random errors will occur. +.P +If +.I ap +is passed to a function that uses +.BI va_arg( ap , type ), +then the value of +.I ap +is undefined after the return of that function. +.SS va_end() +Each invocation of +.BR va_start () +must be matched by a corresponding invocation of +.BR va_end () +in the same function. +After the call +.BI va_end( ap ) +the variable +.I ap +is undefined. +Multiple traversals of the list, each +bracketed by +.BR va_start () +and +.BR va_end () +are possible. +.BR va_end () +may be a macro or a function. +.SS va_copy() +The +.BR va_copy () +macro copies the (previously initialized) variable argument list +.I src +to +.IR dest . +The behavior is as if +.BR va_start () +were applied to +.I dest +with the same +.I last +argument, followed by the same number of +.BR va_arg () +invocations that was used to reach the current state of +.IR src . +.P +.\" Proposal from clive@demon.net, 1997-02-28 +An obvious implementation would have a +.I va_list +be a pointer to the stack frame of the variadic function. +In such a setup (by far the most common) there seems +nothing against an assignment +.P +.in +4n +.EX +va_list aq = ap; +.EE +.in +.P +Unfortunately, there are also systems that make it an +array of pointers (of length 1), and there one needs +.P +.in +4n +.EX +va_list aq; +*aq = *ap; +.EE +.in +.P +Finally, on systems where arguments are passed in registers, +it may be necessary for +.BR va_start () +to allocate memory, store the arguments there, and also +an indication of which argument is next, so that +.BR va_arg () +can step through the list. +Now +.BR va_end () +can free the allocated memory again. +To accommodate this situation, C99 adds a macro +.BR va_copy (), +so that the above assignment can be replaced by +.P +.in +4n +.EX +va_list aq; +va_copy(aq, ap); +\&... +va_end(aq); +.EE +.in +.P +Each invocation of +.BR va_copy () +must be matched by a corresponding invocation of +.BR va_end () +in the same function. +Some systems that do not supply +.BR va_copy () +have +.B __va_copy +instead, since that was the name used in the draft proposal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR va_start (), +.BR va_end (), +.BR va_copy () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR va_arg () +T} Thread safety MT-Safe race:ap +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR va_start () +.TQ +.BR va_arg () +.TQ +.BR va_end () +C89, POSIX.1-2001. +.TP +.BR va_copy () +C99, POSIX.1-2001. +.SH CAVEATS +Unlike the historical +.B varargs +macros, the +.B stdarg +macros do not permit programmers to code a function with no fixed +arguments. +This problem generates work mainly when converting +.B varargs +code to +.B stdarg +code, but it also creates difficulties for variadic functions that wish to +pass all of their arguments on to a function that takes a +.I va_list +argument, such as +.BR vfprintf (3). +.SH EXAMPLES +The function +.I foo +takes a string of format characters and prints out the argument associated +with each format character based on the type. +.P +.EX +#include <stdio.h> +#include <stdarg.h> +\& +void +foo(char *fmt, ...) /* \[aq]...\[aq] is C syntax for a variadic function */ +\& +{ + va_list ap; + int d; + char c; + char *s; +\& + va_start(ap, fmt); + while (*fmt) + switch (*fmt++) { + case \[aq]s\[aq]: /* string */ + s = va_arg(ap, char *); + printf("string %s\en", s); + break; + case \[aq]d\[aq]: /* int */ + d = va_arg(ap, int); + printf("int %d\en", d); + break; + case \[aq]c\[aq]: /* char */ + /* need a cast here since va_arg only + takes fully promoted types */ + c = (char) va_arg(ap, int); + printf("char %c\en", c); + break; + } + va_end(ap); +} +.EE +.SH SEE ALSO +.BR vprintf (3), +.BR vscanf (3), +.BR vsyslog (3) |