diff options
Diffstat (limited to 'man3/stdarg.3')
| -rw-r--r-- | man3/stdarg.3 | 297 |
1 files changed, 0 insertions, 297 deletions
diff --git a/man3/stdarg.3 b/man3/stdarg.3 deleted file mode 100644 index 4168487d0..000000000 --- a/man3/stdarg.3 +++ /dev/null @@ -1,297 +0,0 @@ -'\" 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) |