A function may be called with a variable number of arguments of varying types. As described in 7.7.1, its parameter list contains one or more parameters. The rightmost parameter plays a special role in the access mechanism, and will be designated parmN in this description.

The type declared is

va_list

#include <stdarg.h>
void va_start(va_list ap, parmN);

The va_start macro initializes ap for subsequent use by va_arg and va_end.

The parameter parmN is the identifier of the rightmost parameter in the variable parameter list in the function definition (the one just before the, ...). If the parameter parmN is declared with the register storage class, with a function or array type, or with a type that is not compatible with the type that results after application of the default argument promotions, the behavior is undefined.

#include <stdarg.h>
type va_arg(va_list ap, type);

#include <stdarg.h>
void va_end(va_list ap);

#include <stdarg.h>
#define MAXARGS     31

void f1(int n_ptrs, ....)
{
   va_list ap;
   char *array[MAXARGS];
   int ptr_no = 0;

   if  (n_ptrs > MAXARGS)
      n_ptrs = MAXARGS;
   va_start(ap, n_ptrs);
   while (ptr_no < n_ptrs)
      array[ptr_no++] = va_arg(ap, char *);
   va_end (ap);
   f2(n_ptrs, array);
}

void f1(int, ....);

• You must declare a function explicitly as having a variable argument list. (Call it f.) That means its argument list must end in ellipsis (, ...), both in its definition and any declarations. Moreover, all calls to the function must be in scope of a function prototype that declares the function this way.
• You must declare the function with at least one fixed argument. The last of these fixed arguments is conventionally referred to as parmN.
• You must declare a data object of type va_list, conventionally called ap. The data object must, of course, be visible within the function.
• You must execute va_start(ap, parmN) within f. You must not execute va_list or va_end until you do so.
• You can then execute va_arg(ap,T) in the function or in any of the functions that it calls. You must specify the proper types for each of the arguments, of course, and in the order that they appear in the function call. Note that va_arg is an rvalue macro. You cannot use the macro invocation as an 1value to alter the value stored in the argument data object.
• You must not write a type T that widens when passed as an argument. Replace float with double. Replace char, signed char, unsigned char, short,and unsigned short with either int or unsigned int. Use unsigned int for an unsigned short that is the same size as int. Rarer still, use unsigned int for a character type that represents no negative values and is the same size as int.
• You must write only a type T that can be converted to a pointer type by appending a *. For example, the type designators int and char * are valid. The type designator char (*) [5] is not. As a general rule, be wary of type designators that contain parentheses or brackets.
• You must execute va_end within f if you earlier executed va_start. Once you execute va_end you must not again execute va_arg unless you first execute va_start to initiate a rescan. In that case, you must execute va_end again before the function returns.

fputs("this is a test", stdout);

va_fputs(stdout, "this is", "a test", NULL);

You can write va_fputs as:

include <stdarg.h>
#include <stdout.h>

int va_fputs(FILE *str, ...)
     {    /* write zero or more strings */
     char *s;
     va_list va_list ap;

     va_start(ap, str);
     while (s = va_arg(ap, char *))
          if (fputs(str, s) < 0)
               return (EOF); /* write error */
     va_end (ap);
     return (0);    /* all writes successful */
     }

If you want to rescan a variable argument list you have to be a bit more careful. Execute va_start to initiate each rescan, of course. Execute va_end before the function returns, and only if you execute va_start at least once. I recommend an even safer discipline — execute va_start and va_end within the same loop. That way, you are more certain to execute va_end only when you should.

Many implementations have no need for va_end. The macro expands to code that does nothing. That means that any errors in using this macro become time bombs that may not go off for years. They get more expensive to find and fix with each passing year. Take pains to eliminate the bugs up front.

Another danger lurks in calling a function with the argument ap (the data object of type va_list). In some implementations, it may be an array type. That means that the function parameter actually becomes a pointer to the first element of the va_list array. When the called function executes va_arg, the data object changes in the calling function (called f above).

In other implementations, va_list is not an array type. That means that the argument ap passes by value as it appears to do. When the called function executes va_arg, the data object in the calling function f does not change.

If you process all arguments in the called function, the difference doesn't matter. If you execute va_arg in different function invocations with the "same" ap, however, it can matter. In fact, you get in trouble if your code requires that the va_list data object be shared or if it requires that the data object not be shared.

You can ensure the behavior that you need:

• If the va_list data object must be shared, write the argument as &ap. Declare the corresponding parameter as va_list *pap. Within the function, execute va_arg(*pap, T) to access each argument in the variable argument list.
• If the va_list data object must not be shared, write the argument as ap. Declare the corresponding parameter as va_list xap. Within the function, declare a data object as va_list ap and execute memcpy(ap, xap, sizeof (va_list)). (memcpy is declared in <string.h>.) Execute va_arg(ap, T) to access each argument in the variable argument list.

This article is excerpted from P.J. Plauger, The Standard C Library, (Englewood Cliffs, N.J.: Prentice-Hall 1992).