Argument Macros (The GNU C Library)

#### A.2.2.5 Argument Access Macros ¶

Here are descriptions of the macros used to retrieve variable arguments. These macros are defined in the header file `stdarg.h`.

Data Type: va_list ¶

  The type `va_list` is used for argument pointer variables.

Macro: `void` va_start `(va_list ap, last-required)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This macro initializes the argument pointer variable ap to point to the first of the optional arguments of the current function; last-required must be the last required argument to the function.

Macro: `type` va_arg `(va_list ap, type)` ¶

  Preliminary: | MT-Safe race:ap | AS-Safe | AC-Unsafe corrupt | See POSIX Safety Concepts.

  The `va_arg` macro returns the value of the next optional argument, and modifies the value of ap to point to the subsequent argument. Thus, successive uses of `va_arg` return successive optional arguments.

  The type of the value returned by `va_arg` is type as specified in the call. type must be a self-promoting type (not `char` or `short int` or `float`) that matches the type of the actual argument.

Macro: `void` va_end `(va_list ap)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This ends the use of ap. After a `va_end` call, further `va_arg` calls with the same ap may not work. You should invoke `va_end` before returning from the function in which `va_start` was invoked with the same ap argument.

  In the GNU C Library, `va_end` does nothing, and you need not ever use it except for reasons of portability.

Sometimes it is necessary to parse the list of parameters more than once or one wants to remember a certain position in the parameter list. To do this, one will have to make a copy of the current value of the argument. But `va_list` is an opaque type and one cannot necessarily assign the value of one variable of type `va_list` to another variable of the same type.

Macro: `void` va_copy `(va_list dest, va_list src)` ¶
Macro: `void` __va_copy `(va_list dest, va_list src)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  The `va_copy` macro allows copying of objects of type `va_list` even if this is not an integral type. The argument pointer in dest is initialized to point to the same argument as the pointer in src.

  `va_copy` was added in ISO C99. When building for strict conformance to ISO C90 (‘`gcc -std=c90`’), it is not available. GCC provides `__va_copy`, as an extension, in any standards mode; before GCC 3.0, it was the only macro for this functionality.

  These macros are no longer provided by the GNU C Library, but rather by the compiler.

If you want to use `va_copy` and be portable to pre-C99 systems, you should always be prepared for the possibility that this macro will not be available. On architectures where a simple assignment is invalid, hopefully `va_copy` will be available, so one should always write something like this if concerned about pre-C99 portability:

    {
      va_list ap, save;
      ...
    #ifdef va_copy
      va_copy (save, ap);
    #else
      save = ap;
    #endif
      ...
    }