Loading...
man/FreeBSD/stdarg.3 Libc-1725.40.4 /dev/null
--- Libc/Libc-1725.40.4/man/FreeBSD/stdarg.3
+++ /dev/null
@@ -1,245 +0,0 @@
-.\" 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 .