Loading...
--- /dev/null
+++ Libc/Libc-594.9.4/man/stdarg.3
@@ -0,0 +1,245 @@
+.\" Copyright (c) 1990, 1991, 1993
+.\" 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.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed by the University of
+.\" California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\" may be used to endorse or promote products derived from this software
+.\" without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" @(#)stdarg.3 8.1 (Berkeley) 6/5/93
+.\" $FreeBSD: src/share/man/man3/stdarg.3,v 1.15 2005/01/21 08:36:36 ru Exp $
+.\"
+.Dd October 25, 2002
+.Dt STDARG 3
+.Os
+.Sh NAME
+.Nm stdarg
+.Nd variable argument lists
+.Sh SYNOPSIS
+.In stdarg.h
+.Ft void
+.Fn va_start "va_list ap" last
+.Ft type
+.Fn va_arg "va_list ap" type
+.Ft void
+.Fn va_copy "va_list dest" "va_list src"
+.Ft void
+.Fn va_end "va_list ap"
+.Sh DESCRIPTION
+A function may be called with a varying number of arguments of varying
+types.
+The include file
+.In stdarg.h
+declares a type
+.Pq Em va_list
+and defines three macros for stepping
+through a list of arguments whose number and types are not known to
+the called function.
+.Pp
+The called function must declare an object of type
+.Em va_list
+which is used by the macros
+.Fn va_start ,
+.Fn va_arg ,
+.Fn va_copy ,
+and
+.Fn va_end .
+.Pp
+The
+.Fn va_start
+macro must be called first, and it initializes
+.Fa ap ,
+which can be passed to
+.Fn va_arg
+for each argument to be processed.
+Calling
+.Fn va_end
+signals that there are no further arguments, and causes
+.Fa ap
+to be invalidated.
+Note that each call to
+.Fn va_start
+must be matched by a call to
+.Fn va_end ,
+from within the same function.
+.Pp
+The parameter
+.Fa last
+is the name of the last parameter before the variable argument list,
+i.e., the last parameter of which the calling function knows the type.
+.Pp
+Because the address of this parameter is used in the
+.Fn va_start
+macro, it should not be declared as a register variable, or as a
+function or an array type.
+.Pp
+The
+.Fn va_arg
+macro expands to an expression that has the type and value of the next
+argument in the call.
+The parameter
+.Fa ap
+is the
+.Em va_list Fa ap
+initialized by
+.Fn va_start .
+Each call to
+.Fn va_arg
+modifies
+.Fa ap
+so that the next call returns the next argument.
+The parameter
+.Fa 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
+.Fa type .
+.Pp
+If there is no next argument, or if
+.Fa type
+is not compatible with the type of the actual next argument
+(as promoted according to the default argument promotions),
+random errors will occur.
+.Pp
+The first use of the
+.Fn va_arg
+macro after that of the
+.Fn va_start
+macro returns the argument after
+.Fa last .
+Successive invocations return the values of the remaining
+arguments.
+.Pp
+The
+.Fn va_copy
+macro copies the state of the variable argument list,
+.Fa src ,
+previously initialized by
+.Fn va_start ,
+to the variable argument list,
+.Fa dest ,
+which must not have been previously initialized by
+.Fn va_start ,
+without an intervening call to
+.Fn va_end .
+The state preserved in
+.Fa dest
+is equivalent to calling
+.Fn va_start
+and
+.Fn va_arg
+on
+.Fa dest
+in the same way as was used on
+.Fa src .
+The copied variable argument list can subsequently be passed to
+.Fn va_arg ,
+and must finally be passed to
+.Fn va_end
+when through with it.
+.Pp
+After a variable argument list is invalidated by
+.Fn va_end ,
+it can be reinitialized with
+.Fn va_start
+or made a copy of another variable argument list with
+.Fn va_copy .
+.Sh EXAMPLES
+The function
+.Em foo
+takes a string of format characters and prints out the argument
+associated with each format character based on the type.
+.Bd -literal -offset indent
+void foo(char *fmt, ...)
+{
+ va_list ap, ap2;
+ int d;
+ char c, *s;
+
+ va_start(ap, fmt);
+ va_copy(ap2, ap);
+ while (*fmt)
+ switch(*fmt++) {
+ case 's': /* string */
+ s = va_arg(ap, char *);
+ printf("string %s\en", s);
+ break;
+ case 'd': /* int */
+ d = va_arg(ap, int);
+ printf("int %d\en", d);
+ break;
+ case 'c': /* char */
+ /* Note: char is promoted to int. */
+ c = va_arg(ap, int);
+ printf("char %c\en", c);
+ break;
+ }
+ va_end(ap);
+ ...
+ /* use ap2 to iterate over the arguments again */
+ ...
+ va_end(ap2);
+}
+.Ed
+.Sh COMPATIBILITY
+These macros are
+.Em not
+compatible with the historic macros they replace.
+A backward compatible version can be found in the include
+file
+.In varargs.h .
+.Sh STANDARDS
+The
+.Fn va_start ,
+.Fn va_arg ,
+.Fn va_copy ,
+and
+.Fn va_end
+macros conform to
+.St -isoC-99 .
+.Sh BUGS
+Unlike the
+.Em varargs
+macros, the
+.Nm
+macros do not permit programmers to
+code a function with no fixed arguments.
+This problem generates work mainly when converting
+.Em varargs
+code to
+.Nm
+code,
+but it also creates difficulties for variadic functions that
+wish to pass all of their arguments on to a function
+that takes a
+.Em va_list
+argument, such as
+.Xr vfprintf 3 .