RAD Studio |  |

va_arg, va_end, va_start

Header File

stdarg.h

Category

Variable Argument List Routines

Prototype

void va_start(va_list ap, lastfix);

type va_arg(va_list ap, type);

void va_end(va_list ap);

Description

Implement a variable argument list.

Some C functions, such as vfprintf and vprintf, take variable argument lists in addition to taking a number of fixed (known) parameters. The va_arg, va_end, and va_start macros provide a portable way to access these argument lists. They are used for stepping through a list of arguments when the called function does not know the number and types of the arguments being passed.

The header file stdarg.h declares one type (va_list) and three macros (va_start, va_arg, and va_end).

- va_list: This array holds information needed by va_arg and va_end. When a called function takes a variable argument list, it declares a variable ap of type va_list.
- va_start: This routine (implemented as a macro) sets ap to point to the first of the variable arguments being passed to the function. va_start must be used before the first call to va_arg or va_end.
- va_start takes two parameters: ap and lastfix. (ap is explained under va_list in the preceding paragraph; lastfix is the name of the last fixed parameter being passed to the called function.)
- va_arg: This routine (also implemented as a macro) expands to an expression that has the same type and value as the next argument being passed (one of the variable arguments). The variable ap to va_arg should be the same ap that va_start initialized.

Note: Because of default promotions, you cannot use char, unsigned char
, or float types with va_arg.
Note: The first time va_arg is used, it returns the first argument in the list. Each successive time va_arg is used, it returns the next argument in the list. It does this by first dereferencing ap, and then incrementing ap to point to the following item. va_arg uses the type to both perform the dereference and to locate the following item. Each successive time va_arg is invoked, it modifies ap to point to the next argument in the list.

- va_end: This macro helps the called function perform a normal return. va_end might modify ap in such a way that it cannot be used unless va_start is recalled. va_end should be called after va_arg has read all the arguments; failure to do so might cause strange, undefined behavior in your program.

Return Value

va_start and va_end return no values; va_arg returns the current argument in the list (the one that ap is pointing to).

Example

Copy Code

    #include <stdio.h>
    #include <stdarg.h>
    /* calculate sum of a 0 terminated list */
    void sum(char *msg, ...)
    {
       int total = 0;
       va_list ap;
       int arg;
       va_start(ap, msg);
       while ((arg = va_arg(ap,int)) != 0) {
          total += arg;
       }
       printf(msg, total);
       va_end(ap);
    }
    int main(void) {
       sum("The total of 1+2+3+4 is %d\n", 1,2,3,4,0);
       return 0;
    }

Portability

POSIX | Win32 | ANSI C | ANSI C++
+ | + | + | +

Copyright(C) 2009 Embarcadero Technologies, Inc. All Rights Reserved.
What do you think about this topic? Send feedback!