Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
STDARG(3)		 BSD Library Functions Manual		     STDARG(3)

     stdarg -- variable	argument lists

     #include <stdarg.h>

     va_start(va_list ap, last);

     va_arg(va_list ap,	type);

     va_copy(va_list dest, va_list src);

     va_end(va_list ap);

     A function	may be called with a varying number of arguments of varying
     types.  The include file <stdarg.h> declares a type (va_list) and defines
     three macros for stepping through a list of arguments whose number	and
     types are not known to the	called function.

     The called	function must declare an object	of type	va_list	which is used
     by	the macros va_start(), va_arg(), va_copy(), and	va_end().

     The va_start() macro initializes ap for subsequent	use by va_arg()	and
     va_end(), and must	be called first.

     The parameter 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.

     Because the address of this parameter is used in the va_start() macro, it
     should not	be declared as a register variable, or as a function or	an ar-
     ray type.

     The va_start() macro returns no value.

     The va_arg() macro	expands	to an expression that has the type and value
     of	the next argument in the call.	The parameter ap is the	va_list	ap
     initialized by va_start().	 Each call to va_arg() modifies	ap so that the
     next call returns the next	argument.  The parameter type is a type	name
     specified so that the type	of a pointer to	an object that has the speci-
     fied type can be obtained simply by adding	a * to type.

     If	there is no next argument, or if type is not compatible	with the type
     of	the actual next	argument (as promoted according	to the default argu-
     ment promotions), random errors will occur.

     The first use of the va_arg() macro after that of the va_start() macro
     returns the argument after	last.  Successive invocations return the val-
     ues of the	remaining arguments.

     The va_copy() macro copies	a variable argument list, previously initial-
     ized by va_start(), from src to dest.  The	state is preserved such	that
     it	is equivalent to calling va_start() with the same second argument used
     with src, and calling va_arg() the	same number of times as	called with

     The va_copy() macro returns no value.

     The va_end() macro	handles	a normal return	from the function whose	vari-
     able argument list	was initialized	by va_start().

     The va_end() macro	returns	no value.

     The function foo takes a string of	format characters and prints out the
     argument associated with each format character based on the type.

	   void	foo(char *fmt, ...)
		   va_list ap;
		   int d;
		   char	c, *s;

		   va_start(ap,	fmt);
		   while (*fmt)
			   switch(*fmt++) {
			   case	's':			   /* string */
				   s = va_arg(ap, char *);
				   printf("string %s\n", s);
			   case	'd':			   /* int */
				   d = va_arg(ap, int);
				   printf("int %d\n", d);
			   case	'c':			   /* char */
				   /* Note: char is promoted to	int. */
				   c = va_arg(ap, int);
				   printf("char	%c\n", c);

     The va_start(), va_arg(), va_copy(), and va_end() macros conform to
     ISO/IEC 9899:1999 ("ISO C99").

     These macros are not compatible with the historic macros they replace.  A
     backward compatible version can be	found in the include file <varargs.h>.

     Unlike the	varargs	macros,	the stdarg macros do not permit	programmers to
     code a function with no fixed arguments.  This problem generates work
     mainly when converting varargs code to stdarg code, but it	also creates
     difficulties for variadic functions that wish to pass all of their	argu-
     ments on to a function that takes a va_list argument, such	as

BSD			       October 25, 2002				   BSD


Want to link to this manual page? Use this URL:

home | help