usr/src/share/man/man3/stdarg.3

.\"	@(#)stdarg.3	6.1 (Berkeley) %G%
.\"
.TH VARARGS 3  ""
.AT 3
.SH NAME
varargs \- variable argument list
.SH SYNOPSIS
.B "#include <varargs.h>"
.PP
.I function\c
.RB ( va_alist )
.br
.B va_dcl
.br
.B va_list
.IR pvar ;
.br
.B va_start\c
.RI ( pvar );
.br
f =
.B va_arg\c
.RI ( pvar ,
.IR type );
.br
.B va_end\c
.RI ( pvar );
.SH DESCRIPTION
This set of macros provides a means of writing portable procedures that
accept variable argument lists.
Routines having variable argument lists (such as
.IR printf (3))
that do not use varargs are inherently nonportable, since different
machines use different argument passing conventions.
.PP
.B va_alist
is used in a function header to declare a variable argument list.
.PP
.B va_dcl
is a declaration for
.BR va_alist .
Note that there is no semicolon after
.B va_dcl.
.PP
.B va_list
is a type which can be used for the variable
.IR pvar ,
which is used to traverse the list.
One such variable must always be declared.
.PP
.B va_start\c
.RI (pvar)
is called to initialize
.I pvar
to the beginning of the list.
.PP
.B va_arg\c
.RI ( pvar ,
.IR type )
will return the next argument in the list pointed to by
.IR pvar .
.I Type
is the type the argument is expected to be.
Different types can be mixed, but it is up
to the routine to know what type of argument is
expected, since it cannot be determined at runtime.
.PP
.B va_end\c
.RI ( pvar )
is used to finish up.
.PP
Multiple traversals, each bracketed by
.B va_start
\&...
.B va_end,
are possible.
.SH EXAMPLE
.nf
	\fB#include\fP <varargs.h>
	execl(\fBva_alist\fP)
	\fBva_dcl\fP
	{
		\fBva_list\fP ap;
		\fBchar\fP *file;
		\fBchar\fP *args[100];
		\fBint\fP argno = 0;

		\fBva_start\fP(ap);
		file = \fBva_arg(ap, \fBchar\fP *);
		\fBwhile\fP (args[argno++] = \fBva_arg\fP(ap, \fBchar\fP *))
			\fB;\fP
		\fBva_end\fP(ap);
		\fBreturn\fP execv(file, args);
	}
.fi
.SH BUGS
It is up to the calling routine to determine how many arguments
there are, since it is not possible to determine this from the
stack frame.  For example,
.I execl
passes a 0 to signal the end of the list.
.I Printf
can tell how many arguments are supposed to be there by the format.
Commit	Line	Data
	1	.\" @(#)stdarg.3 6.1 (Berkeley) %G%
	2	.\"
	3	.TH VARARGS 3 ""
	4	.AT 3
	5	.SH NAME
	6	varargs \- variable argument list
	7	.SH SYNOPSIS
	8	.B "#include <varargs.h>"
	9	.PP
	10	.I function\c
	11	.RB ( va_alist )
	12	.br
	13	.B va_dcl
	14	.br
	15	.B va_list
	16	.IR pvar ;
	17	.br
	18	.B va_start\c
	19	.RI ( pvar );
	20	.br
	21	f =
	22	.B va_arg\c
	23	.RI ( pvar ,
	24	.IR type );
	25	.br
	26	.B va_end\c
	27	.RI ( pvar );
	28	.SH DESCRIPTION
	29	This set of macros provides a means of writing portable procedures that
	30	accept variable argument lists.
	31	Routines having variable argument lists (such as
	32	.IR printf (3))
	33	that do not use varargs are inherently nonportable, since different
	34	machines use different argument passing conventions.
	35	.PP
	36	.B va_alist
	37	is used in a function header to declare a variable argument list.
	38	.PP
	39	.B va_dcl
	40	is a declaration for
	41	.BR va_alist .
	42	Note that there is no semicolon after
	43	.B va_dcl.
	44	.PP
	45	.B va_list
	46	is a type which can be used for the variable
	47	.IR pvar ,
	48	which is used to traverse the list.
	49	One such variable must always be declared.
	50	.PP
	51	.B va_start\c
	52	.RI (pvar)
	53	is called to initialize
	54	.I pvar
	55	to the beginning of the list.
	56	.PP
	57	.B va_arg\c
	58	.RI ( pvar ,
	59	.IR type )
	60	will return the next argument in the list pointed to by
	61	.IR pvar .
	62	.I Type
	63	is the type the argument is expected to be.
	64	Different types can be mixed, but it is up
	65	to the routine to know what type of argument is
	66	expected, since it cannot be determined at runtime.
	67	.PP
	68	.B va_end\c
	69	.RI ( pvar )
	70	is used to finish up.
	71	.PP
	72	Multiple traversals, each bracketed by
	73	.B va_start
	74	\&...
	75	.B va_end,
	76	are possible.
	77	.SH EXAMPLE
	78	.nf
	79	\fB#include\fP <varargs.h>
	80	execl(\fBva_alist\fP)
	81	\fBva_dcl\fP
	82	{
	83	\fBva_list\fP ap;
	84	\fBchar\fP *file;
	85	\fBchar\fP *args[100];
	86	\fBint\fP argno = 0;
	87
	88	\fBva_start\fP(ap);
	89	file = \fBva_arg(ap, \fBchar\fP *);
	90	\fBwhile\fP (args[argno++] = \fBva_arg\fP(ap, \fBchar\fP *))
	91	\fB;\fP
	92	\fBva_end\fP(ap);
	93	\fBreturn\fP execv(file, args);
	94	}
	95	.fi
	96	.SH BUGS
	97	It is up to the calling routine to determine how many arguments
	98	there are, since it is not possible to determine this from the
	99	stack frame. For example,
	100	.I execl
	101	passes a 0 to signal the end of the list.
	102	.I Printf
	103	can tell how many arguments are supposed to be there by the format.