<stdarg.h>

Include the standard header <stdarg.h> to access the unnamed additional arguments (arguments with no corresponding parameter declarations) in a function that accepts a varying number of arguments. To access the additional arguments:

• The program must first execute the macro va_start within the body of the function to initialize an object with context information.
• Subsequent execution of the macro va_arg, designating the same context information, yields the values of the additional arguments in order, beginning with the first unnamed argument. You can execute the macro va_arg from any function that can access the context information saved by the macro va_start.
• If you have executed the macro va_start in a function, you must execute the macro va_end in the same function, designating the same context information, before the function returns.

You can repeat this sequence (as needed) to access the arguments as often as you want.

You declare an object of type va_list to store context information. va_list can be either an array type or a non-array type. Whether or not va_list is an array type affects how the program shares context information with functions that it calls. The address of the first element of an array is passed, rather than the object itself. So an array type is effectively passed by reference, while a non-array type is passed by value.

For example:

#include <stdarg.h>
void va_cat(char *s, ...)
    {
    char *t;
    va_list ap;

    va_start(ap, s);
    while (t = va_arg(ap, char *)) null pointer ends list
        {
        s += strlen(s);            skip to end
        strcpy(s, t);              and copy a string
        }
    va_end(ap);
    }

The function va_cat concatenates an arbitrary number of strings onto the end of an existing string (assuming that the existing string is stored in an object large enough to hold the resulting string).

#define va_arg(va_list ap, Ty) <rvalue of type Ty>
#define va_end(va_list ap) <void expression>
#define va_start(va_list ap, last-par) <void expression>
typedef do-type va_list;

va_arg

#define va_arg(va_list ap, Ty) <rvalue of type Ty>

The macro yields the value of the next argument in order, specified by the context information designated by ap. The additional argument must be of object type Ty after applying the rules for promoting arguments in the absence of a function prototype.

va_end

#define va_end(va_list ap) <void expression>

The macro performs any cleanup necessary, after processing the context information designated by ap, so that the function can return.

va_list

typedef do-type va_list;

The type is the object type do-type that you declare to hold the context information initialized by va_start and used by va_arg to access additional unnamed arguments.

va_start

#define va_start(va_list ap, last-par) <void expression>

The macro stores initial context information in the object designated by ap. last-par is the name of the last parameter you declare. For example, last-par is b for the function declared as int f(int a, int b, ...). The last parameter must not have register storage class, and it must have a type that is not changed by the translator. It cannot have:

• an array type
• a function type
• type float
• any integer type that changes when promoted
• a reference type [C++ only]

See also the Table of Contents and the Index.

Copyright © 1989-2002 by P.J. Plauger and Jim Brodie. All rights reserved.