1. Variable Argument Lists

The printf family of functions is defined to accept a variable number of arguments, rather than a fixed argument list. You can define your own functions with a variable argument list, by using macro definitions from either ‘stdarg.h’ (for compatibility with ANSI C) or from ‘varargs.h’ (for compatibility with a popular convention prior to ANSI C).

1.1 ANSI-standard macros, ‘stdarg.h’

In ANSI C, a function has a variable number of arguments when its parameter list ends in an ellipsis (...). The parameter list must also include at least one explicitly named argument; that argument is used to initialize the variable list data structure.

ANSI C defines three macros (va_start, va_arg, and va_end) to operate on variable argument lists. ‘stdarg.h’ also defines a special type to represent variable argument lists: this type is called va_list.

1.1.1 Initialize variable argument list

Synopsis

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

Description
Use va_start to initialize the variable argument list ap, so that va_arg can extract values from it. rightmost is the name of the last explicit argument in the parameter list (the argument immediately preceding the ellipsis ‘...’ that flags variable arguments in an ANSI C function header). You can only use va_start in a function declared using this ellipsis notation (not, for example, in one of its subfunctions).

Returns
va_start does not return a result.

Portability
ANSI C requires va_start.

1.1.2 Extract a value from argument list

Synopsis

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

Description
va_arg returns the next unprocessed value from a variable argument list ap (which you must previously create with va_start). Specify the type for the value as the second parameter to the macro, type.

You may pass a va_list object ap to a subfunction, and use va_arg from the subfunction rather than from the function actually declared with an ellipsis in the header; however, in that case you may only use va_arg from the subfunction. ANSI C does not permit extracting successive values from a single variable-argument list from different levels of the calling stack.

There is no mechanism for testing whether there is actually a next argument available; you might instead pass an argument count (or some other data that implies an argument count) as one of the fixed arguments in your function call.

Returns
va_arg returns the next argument, an object of type type.

Portability
ANSI C requires va_arg.

1.1.3 Abandon a variable argument list

Synopsis

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

Description
Use va_end to declare that your program will not use the variable argument list ap any further.

Returns
va_end does not return a result.

Portability
ANSI C requires va_end.

1.2 Traditional macros, ‘varargs.h’

If your C compiler predates ANSI C, you may still be able to use variable argument lists using the macros from the ‘varargs.h’ header file. These macros resemble their ANSI counterparts, but have important differences in usage. In particular, since traditional C has no declaration mechanism for variable argument lists, two additional macros are provided simply for the purpose of defining functions with variable argument lists.

As with ‘stdarg.h’, the type va_list is used to hold a data structure representing a variable argument list.

1.2.1 Declare variable arguments

Synopsis

#include <varargs.h>
function(va_alist)
va_dcl

Description
To use the ‘varargs.h’ version of variable argument lists, you must declare your function with a call to the macro va_alist as its argument list, and use va_dcl as the declaration. Do not use a semicolon after va_dcl.

Returns
These macros cannot be used in a context where a return is syntactically possible.

Portability
va_alist and va_dcl were the most widespread method of declaring variable argument lists prior to ANSI C.

1.2.2 Initialize variable argument list

Synopsis

#include <varargs.h>
va_list ap;
va_start(ap);

Description
With the ‘varargs.h’ macros, use va_start to initialize a data structure ap to permit manipulating a variable argument list. ap must have the type va_alist.

Returns
va_start does not return a result.

Portability
va_start is also defined as a macro in ANSI C, but the definitions are incompatible; the ANSI version has another parameter besides ap.

1.2.3 Extract a value from argument list

Synopsis

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

Description
va_arg returns the next unprocessed value from a variable argument list ap (which you must previously create with va_start). Specify the type for the value as the second parameter to the macro, type.

Returns
va_arg returns the next argument, an object of type type.

Portability
The va_arg defined in ‘varargs.h’ has the same syntax and usage as the ANSI C version from ‘stdarg.h’.

1.2.4 Abandon a variable argument list

Synopsis

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

Description
Use va_end to declare that your program will not use the variable argument list ap any further.

Returns
va_end does not return a result.

Portability
The va_end defined in ‘varargs.h’ has the same syntax and usage as the ANSI C version from ‘stdarg.h’.

Index

Table of Contents

About This Document

This document was generated by Santa Cruz Build on January, 10 2009 using texi2html 1.78.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated by Santa Cruz Build on January, 10 2009 using texi2html 1.78.