varargs(0)                          CLIX                          varargs(0)



  NAME

    varargs - Handles variable argument list for C language functions

  SYNOPSIS

    #include <varargs.h>

    va_alist

    va_dcl

    void va_start(
      va_list pvar );

    type va_arg(
      va_list pvar ,

      type );

    void va_end(
      va_list pvar );

  DESCRIPTION

    This set of macros provides a portable way for C language functions to
    access variable argument lists.  A variable argument list is one that may
    contain arguments that are variable both with respect to number and type.
    The actual number of arguments and type of each argument is determined in
    accordance with a programmer-defined convention.

    On the Clipper these macros provide an interface between the programmer
    and the C compiler.  The compiler checks for the macro expansion and is
    able to locate each argument, whether it is in registers or on the call
    stack.

    Functions that have variable argument lists (such as printf()) but do not
    use varargs() are inherently nonportable, as different machines use
    different argument-passing conventions.

    The set of macros includes the following:

    va_alist   Used as the parameter list in a function header.

    va_dcl     Is the sole declaration for the function.  No semicolon should
               follow va_dcl.

    va_list    Defines a single variable used by the other macros to record
               current state when traversing the argument list.  The SYNOPSIS,
               DESCRIPTION, and EXAMPLES sections use the name pvar for this
               variable.



  2/94 - Intergraph Corporation                                              1

  varargs(0)                          CLIX                          varargs(0)



    va_start   Initializes the variable pvar to the beginning of the list.

    va_arg     Used in expression context to return the next argument in the
               list pointed to by pvar and to advance pvar to point to the
               subsequent argument.  The va_type parameter is the type the
               argument is known to be; it is also the type of the resulting
               expression.  Arguments in the list may be of mixed types; any
               particular argument may be of any type.  It is up to the called
               function to know by some predefined convention what type of
               argument is expected, as the argument itself cannot be queried
               to determine its type.  It is also up to the called function to
               determine how many arguments are to accessed.

    va_end     Cleans up.

    Multiple traversals are possible, each being bracketed by va_start ...
    va_end.

  EXAMPLE

    In the following example, function vf() accepts a variable argument list.
    This argument list consists of an integer type code followed by a numeric
    argument of the specified type.  The list ends when a type argument of
    E_PAR is encountered.

    #include <varargs.h>

      /* ---argument type codes--- */
    #define D_PAR 1  /* next parameter is a double */
    #define I_PAR 2  /* next parameter is an int */
    #define E_PAR 3  /* end of parameter list */

    void vf(va_alist)
    va_dcl
    {
         int ptype;
         va_list pvar; /* declare list state variable */

         printf("\nvf: called\n");
         va_start(pvar); /* initialize pvar to first argument */
         while ((ptype = va_arg(pvar, int)) != E_PAR) { /* get type */
              switch (ptype) {  /* obtain and print argument */
              case I_PAR:
                   printf(" type int    = %d\n", va_arg(pvar, int));
                   break;
              case D_PAR:
                   printf(" type double = %f\n", va_arg(pvar, double));
                   break;
              default:
                   printf(" UNKNOWN PARAMETER TYPE\n");
                   return;



  2                                              Intergraph Corporation - 2/94

  varargs(0)                          CLIX                          varargs(0)



              }
         }
         va_end(pvar);    /* clean up */
    }

    /* --- driver for functionvf --- */
    main ()
    {
         vf(D_PAR, 3.4, I_PAR, 45, E_PAR);
         vf(I_PAR, 12, I_PAR, 34 D_PAR, 5.67, E_PAR);
    }

    When this function executes, the following results are produced:

    vf: called
     type double = 3.400000
     type int    = 45

    vf: called
     type int    = 12
     type int    = 34
     type double = 5.670000


  FILES

    /usr/include/sys/varargs.h

  NOTES

    It is nonportable to specify a second argument of char, short, or float to
    va_arg, since arguments seen by the called function are not char, short,
    or float.  The C language converts char and short arguments to int and
    converts float arguments to double before passing them to a function.

  RELATED INFORMATION

    Functions:  vprintf(3)
















  2/94 - Intergraph Corporation                                              3