February 4, 2002 VARARGS 3

### NAME

varargs - variable argument lists

### SYNOPSIS

```void` va_start(```va_list ap`)
```type` va_arg(```va_list ap``, type`)
```void` va_end(```va_list ap`)

### DESCRIPTION

These historic interfaces are provided to support compilation of existing programs only. New code should use the stdarg(3) interfaces.

A function may be called with a varying number of arguments of varying types. The include file <```varargs.h`> declares a type (va_list) and defines three macros for stepping through a list of arguments whose number and types are not known to the called function.

The called function must name an argument ```va_alist`, which marks the start of the variable argument list, and which is naturally the last argument named. It is declared by ```va_dcl`, which should not be followed by a semicolon. The called function also must declare an object of type va_list which is used by the macros va_start(``), va_arg(``), and va_end(``).

The va_start(``) macro initializes ```ap` for subsequent use by va_arg(``) and va_end(``), and must be called first.

It is possible for ```va_alist` to be the only parameter to a function, resulting in it being possible for a function to have no fixed arguments preceding the variable argument list.

The va_start(``) macro returns no value.

The va_arg(``) macro expands to an expression that has the type and value of the next argument in the call. The parameter ```ap` is the va_list`` `ap` initialized by va_start(``). Each call to va_arg(``) modifies ```ap` so that the next call returns the next argument. The parameter ```type` is a type name specified so that the type of a pointer to an object that has the specified type can be obtained simply by adding a * to ```type`.

If there is no next argument, or if ```type` is not compatible with the type of the actual next argument (as promoted according to the default argument promotions), random errors will occur.

The first use of the va_arg(``) macro after that of the va_start(``) macro returns the argument after ```last`. Successive invocations return the values of the remaining arguments.

The va_end(``) macro handles a normal return from the function whose variable argument list was initialized by va_start(``).

The va_end(``) macro returns no value.

### EXAMPLES

The function foo takes a string of format characters and prints out the argument associated with each format character based on the type.

  `

      void foo(fmt, va_alist)
              char *fmt;
              va_dcl
      {
              va_list ap;
              int d;
              char c, *p, *s;

              va_start(ap);
              while (*fmt) {
                      switch (*fmt++) {
                      case 's':                       /* string */
                              s = va_arg(ap, char *);
                              printf("string %s\n", s);
                              break;
                      case 'd':                       /* int */
                              d = va_arg(ap, int);
                              printf("int %d\n", d);
                              break;
                      case 'c':                       /* char */
                              c = va_arg(ap, char);
                              printf("char %c\n", c);
                              break;
                      }
              }
              va_end(ap);
      }

  `

### SEE ALSO

stdarg(3)

### STANDARDS

These historic macros were replaced in ANSI X3.159-1989 (``ANSI C89'') by the include file <```stdarg.h`>; see stdarg(3) for its description.

### COMPATIBILITY

These macros are not compatible with the new macros they were replaced by. In particular, it is not possible for a stdarg function to have no fixed arguments.