va_arg, va_end, va_start

raw OCR

Implement a variable argument list.

Defined in header <stdarg.h>

Syntax

#include <stdarg.h>
void va_start(va_list ap, lastfix);
type va_arg(va_list  ap, type);
void va_end(va_list   ap);

Portability

DOS	UNIX	Windows	ANSI C	C++ only
■	■	■	■

Remarks

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 (vajist) 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 vajist.

va_start: This routine (implemented as a macro) sets np 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 vajist 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.

Because of default promotions, you can't use char, unsigned char, or float types with va_arg.

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 Hst.

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

#include <stdio.h>
#include <stdarg.h>

/* calculate sum of a    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(insg, total);
   va_end(ap) ;
}
int main (void) {
   sumC'The total of  1+2+3+4 is %d\n", 1,2,3,4,
   return 0;
}

Program    output

The total of 1+2+3+4  is 10

#include <stdio.h>
#include <stdarg.h>
void error (char *format,...)
{
   va_list argptr;
   printf ("Error: ");
   va_start (argptr, format);
   vprintf (format, argptr);
   va_end (argptr);
}
int main (void) {
   int value = -1;
   error ("This is just an error message\n");
   error ("Invalid value %d encountered\n", value)
   return 0;

Program    output

Error: This is just an  error message
Error: Invalid value  -1 encountered

Differences from modern implementations

Nothing recorded yet.

Modern references

These are search links, not yet checked by hand.

Stable link: /3.1/stdarg.h/va_arg/ · short form /3.1/va_arg/