summaryrefslogtreecommitdiffstats
path: root/man3/stdarg.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/stdarg.3')
-rw-r--r--man3/stdarg.3297
1 files changed, 0 insertions, 297 deletions
diff --git a/man3/stdarg.3 b/man3/stdarg.3
deleted file mode 100644
index ce04704..0000000
--- 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 2023-10-31 "Linux man-pages 6.7"
-.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)