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

FreeBSD Manual Pages


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

     va_start, va_arg, va_copy,	va_end -- variable argument lists

     #include <stdarg.h>

     va_start(va_list ap, last);

     va_arg(va_list ap,	type);

     va_copy(va_list dst, 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_end(), and,	optionally, va_copy().

     The va_start() macro initializes ap for subsequent	use by va_arg(),
     va_copy() 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, nor	as a function, nor an
     array type.

     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, see below), random errors	will occur.

     If	the type in question is	one that would normally	be promoted, the pro-
     moted type	should be used as the argument to va_arg().  The following de-
     scribes which types should	be promoted (and to what):
     -	 short is promoted to int
     -	 float is promoted to double
     -	 char is promoted to int

     The same rules apply to unsigned versions of the above types, as well as
     their bit-type equivalents	(e.g. int8_t and int16_t).

     The va_copy() macro makes dst a copy of src as if the va_start() macro
     had been applied to it followed by	the same sequence of uses of the
     va_arg() macro as had previously been used	to reach the present state of

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

     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_start(), va_copy() and va_end() macros return 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.

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

		   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 */
				   c = va_arg(ap, int);	   /* promoted */
				   printf("char	%c\n", c);
			   case	'f':			   /* float */
				   f = va_arg(ap, double); /* promoted */
				   printf("float %f\n",	f);

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

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

     The va_start(), va_arg() and va_end() macros were introduced in ANSI
     X3.159-1989 ("ANSI	C89").	The va_copy() macro was	introduced in ISO/IEC
     9899:1999 ("ISO C99").

     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 an argument of type va_list, such as

BSD			       November	10, 2015			   BSD


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

home | help