VARARGS(3,L)                AIX Technical Reference                VARARGS(3,L)



-------------------------------------------------------------------------------
varargs



PURPOSE

Handles a variable-length parameter list.

LIBRARY

Standard C Library (libc.a)

SYNTAX

#include <varargs.h>




                va_alist                    type va_arg (argp, type)
                                            va_list argp;
                va_dcl
                                            void va_end (argp)
                void va_start (argp)        va_list argp;
                va_list argp;



DESCRIPTION

This set of macros allows you to write portable subroutines that accept a
variable number of parameters.  Subroutines that have variable-length parameter
lists (such as printf), but that do not use varargs, are inherently nonportable
because different systems use different parameter-passing conventions.

va_alist
        Is used as the parameter list in the function header.

va_dcl  Is the declaration for va_alist.  No semicolon should follow va_dcl.

va_list Defines the type of the variable used to traverse the list.

va_start
        Initializes argp to point to the beginning of the list.

argp    Is a variable that the varargs macros use to keep track of the current
        location in the parameter list.  Do not modify this variable.

va_arg  Returns the next parameter in the list pointed to by argp.  type is the
        data type that the parameter is expected to be.  Different types can be
        mixed, but your subroutine must know what type of parameter is expected



Processed November 7, 1990       VARARGS(3,L)                                 1

VARARGS(3,L)                AIX Technical Reference                VARARGS(3,L)



        because it cannot be determined at runtime.  The printf subroutine
        solves this problem by using its format parameter to determine the
        parameter types expected.

va_end  Cleans up at the end.

Your subroutine can traverse, or scan, the parameter list more than once.
Start each traversal with a call to va_start and end it with var_end.

Note:  The calling routine is responsible for specifying the number of
       parameters because it is not always possible to determine this from the
       stack frame.  For example, execl is passed a NULL pointer to signal the
       end of the list.  printf determines the number of parameters from its
       format parameter.

       Specifying char, short, or float as the second parameter to va_arg is
       not portable because parameters seen by the called subroutine are not
       char, short, or float.  The C complier converts char and short
       parameters to int, and it converts float parameters to double before
       passing them to a subroutine.

EXAMPLE

The following code example is a possible alternate implementation of execl
system call:

  #include <varargs.h>

  #define MAXARGS 100
  /*
  **  execl is called by
  **  execl(file, arg1, arg2,..., (char *) 0);
  */
  execl(va_alist)
     va_dcl
  {
     va_list ap;
     char *file;
     char *args[MAXARGS];
     int argno = 0;

     va_start(ap);
     file = va_arg(ap, char *);
     while ((args[argno++] = va_arg(ap, char *)) != (char *) 0)
        ;   /* Empty loop body */
     va_end(ap);
     return (execv(file, args));
  }

RELATED INFORMATION





Processed November 7, 1990       VARARGS(3,L)                                 2

VARARGS(3s,L)               AIX Technical Reference               VARARGS(3s,L)



In this book:  "exec:  execl, execv, execle, execve, execlp, execvp," "printf,
fprintf, sprintf, NLprintf, NLfprintf, NLsprintf, wsprintf," and "vprintf,
vfprintf, vsprintf, NLvprintf, NLvfprintf, NLvsprintf."




















































Processed November 7, 1990       VARARGS(3s,L)                                3