[apple/libc.git] / man / stdarg.3

.\" 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 .
Commit	Line	Data
224c7076 A	1	.\" Copyright (c) 1990, 1991, 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" the American National Standards Committee X3, on Information
	6	.\" Processing Systems.
	7	.\"
	8	.\" Redistribution and use in source and binary forms, with or without
	9	.\" modification, are permitted provided that the following conditions
	10	.\" are met:
	11	.\" 1. Redistributions of source code must retain the above copyright
	12	.\" notice, this list of conditions and the following disclaimer.
	13	.\" 2. Redistributions in binary form must reproduce the above copyright
	14	.\" notice, this list of conditions and the following disclaimer in the
	15	.\" documentation and/or other materials provided with the distribution.
	16	.\" 3. All advertising materials mentioning features or use of this software
	17	.\" must display the following acknowledgement:
	18	.\" This product includes software developed by the University of
	19	.\" California, Berkeley and its contributors.
	20	.\" 4. Neither the name of the University nor the names of its contributors
	21	.\" may be used to endorse or promote products derived from this software
	22	.\" without specific prior written permission.
	23	.\"
	24	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	25	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	26	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	27	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	28	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	29	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	30	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	31	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	32	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	33	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	34	.\" SUCH DAMAGE.
	35	.\"
	36	.\" @(#)stdarg.3 8.1 (Berkeley) 6/5/93
34e8f829	37	.\" $FreeBSD: src/share/man/man3/stdarg.3,v 1.15 2005/01/21 08:36:36 ru Exp $
224c7076	38	.\"
34e8f829	39	.Dd October 25, 2002
224c7076 A	40	.Dt STDARG 3
	41	.Os
	42	.Sh NAME
	43	.Nm stdarg
	44	.Nd variable argument lists
	45	.Sh SYNOPSIS
34e8f829	46	.In stdarg.h
224c7076 A	47	.Ft void
	48	.Fn va_start "va_list ap" last
	49	.Ft type
	50	.Fn va_arg "va_list ap" type
	51	.Ft void
34e8f829 A	52	.Fn va_copy "va_list dest" "va_list src"
34e8f829 A	53	.Ft void
224c7076 A	54	.Fn va_end "va_list ap"
	55	.Sh DESCRIPTION
	56	A function may be called with a varying number of arguments of varying
	57	types.
	58	The include file
34e8f829	59	.In stdarg.h
224c7076 A	60	declares a type
	61	.Pq Em va_list
	62	and defines three macros for stepping
	63	through a list of arguments whose number and types are not known to
	64	the called function.
	65	.Pp
	66	The called function must declare an object of type
	67	.Em va_list
	68	which is used by the macros
	69	.Fn va_start ,
	70	.Fn va_arg ,
34e8f829	71	.Fn va_copy ,
224c7076 A	72	and
	73	.Fn va_end .
	74	.Pp
	75	The
	76	.Fn va_start
34e8f829 A	77	macro must be called first, and it initializes
	78	.Fa ap ,
	79	which can be passed to
224c7076	80	.Fn va_arg
34e8f829 A	81	for each argument to be processed.
	82	Calling
	83	.Fn va_end
	84	signals that there are no further arguments, and causes
	85	.Fa ap
	86	to be invalidated.
	87	Note that each call to
	88	.Fn va_start
	89	must be matched by a call to
224c7076	90	.Fn va_end ,
34e8f829	91	from within the same function.
224c7076 A	92	.Pp
	93	The parameter
	94	.Fa last
	95	is the name of the last parameter before the variable argument list,
34e8f829	96	i.e., the last parameter of which the calling function knows the type.
224c7076 A	97	.Pp
	98	Because the address of this parameter is used in the
	99	.Fn va_start
	100	macro, it should not be declared as a register variable, or as a
	101	function or an array type.
	102	.Pp
	103	The
224c7076 A	104	.Fn va_arg
	105	macro expands to an expression that has the type and value of the next
	106	argument in the call.
	107	The parameter
	108	.Fa ap
34e8f829	109	is the
224c7076 A	110	.Em va_list Fa ap
	111	initialized by
	112	.Fn va_start .
34e8f829	113	Each call to
224c7076 A	114	.Fn va_arg
	115	modifies
	116	.Fa ap
	117	so that the next call returns the next argument.
	118	The parameter
	119	.Fa type
	120	is a type name specified so that the type of a pointer to an
34e8f829	121	object that has the specified type can be obtained simply by
224c7076 A	122	adding a *
	123	to
	124	.Fa type .
	125	.Pp
	126	If there is no next argument, or if
	127	.Fa type
	128	is not compatible with the type of the actual next argument
	129	(as promoted according to the default argument promotions),
	130	random errors will occur.
	131	.Pp
	132	The first use of the
	133	.Fn va_arg
34e8f829	134	macro after that of the
224c7076	135	.Fn va_start
34e8f829	136	macro returns the argument after
224c7076 A	137	.Fa last .
	138	Successive invocations return the values of the remaining
	139	arguments.
	140	.Pp
	141	The
34e8f829 A	142	.Fn va_copy
	143	macro copies the state of the variable argument list,
	144	.Fa src ,
	145	previously initialized by
	146	.Fn va_start ,
	147	to the variable argument list,
	148	.Fa dest ,
	149	which must not have been previously initialized by
	150	.Fn va_start ,
	151	without an intervening call to
	152	.Fn va_end .
	153	The state preserved in
	154	.Fa dest
	155	is equivalent to calling
	156	.Fn va_start
	157	and
	158	.Fn va_arg
	159	on
	160	.Fa dest
	161	in the same way as was used on
	162	.Fa src .
	163	The copied variable argument list can subsequently be passed to
	164	.Fn va_arg ,
	165	and must finally be passed to
224c7076	166	.Fn va_end
34e8f829	167	when through with it.
224c7076	168	.Pp
34e8f829 A	169	After a variable argument list is invalidated by
	170	.Fn va_end ,
	171	it can be reinitialized with
	172	.Fn va_start
	173	or made a copy of another variable argument list with
	174	.Fn va_copy .
224c7076 A	175	.Sh EXAMPLES
	176	The function
	177	.Em foo
	178	takes a string of format characters and prints out the argument
	179	associated with each format character based on the type.
	180	.Bd -literal -offset indent
	181	void foo(char *fmt, ...)
	182	{
34e8f829	183	va_list ap, ap2;
224c7076	184	int d;
34e8f829	185	char c, *s;
224c7076 A	186
224c7076 A	187	va_start(ap, fmt);
34e8f829	188	va_copy(ap2, ap);
224c7076 A	189	while (*fmt)
	190	switch(*fmt++) {
	191	case 's': /* string */
	192	s = va_arg(ap, char *);
	193	printf("string %s\en", s);
	194	break;
	195	case 'd': /* int */
	196	d = va_arg(ap, int);
	197	printf("int %d\en", d);
	198	break;
	199	case 'c': /* char */
34e8f829 A	200	/* Note: char is promoted to int. */
34e8f829 A	201	c = va_arg(ap, int);
224c7076 A	202	printf("char %c\en", c);
	203	break;
	204	}
	205	va_end(ap);
34e8f829 A	206	...
	207	/* use ap2 to iterate over the arguments again */
	208	...
	209	va_end(ap2);
224c7076 A	210	}
224c7076 A	211	.Ed
34e8f829 A	212	.Sh COMPATIBILITY
	213	These macros are
	214	.Em not
	215	compatible with the historic macros they replace.
	216	A backward compatible version can be found in the include
	217	file
	218	.In varargs.h .
224c7076 A	219	.Sh STANDARDS
	220	The
	221	.Fn va_start ,
	222	.Fn va_arg ,
34e8f829	223	.Fn va_copy ,
224c7076 A	224	and
	225	.Fn va_end
	226	macros conform to
34e8f829	227	.St -isoC-99 .
224c7076 A	228	.Sh BUGS
	229	Unlike the
	230	.Em varargs
	231	macros, the
34e8f829	232	.Nm
224c7076 A	233	macros do not permit programmers to
	234	code a function with no fixed arguments.
	235	This problem generates work mainly when converting
	236	.Em varargs
	237	code to
34e8f829	238	.Nm
224c7076 A	239	code,
	240	but it also creates difficulties for variadic functions that
	241	wish to pass all of their arguments on to a function
	242	that takes a
	243	.Em va_list
	244	argument, such as
	245	.Xr vfprintf 3 .