unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

VARARGS(3)                 Library Functions Manual                 VARARGS(3)



NAME
       varargs - handle variable argument list

SYNOPSIS
       #include <&lt;varargs.h>&gt;

       function(va_alist) va_dcl

       va_list pvar;

       va_start(pvar);

       f = va_arg(pvar, type);

       va_end(pvar);

DESCRIPTION
       This set of macros provides a means of writing portable procedures that
       accept variable argument  lists.   Routines  having  variable  argument
       lists (such as printf(3V)) but do not use varargs() are inherently non-
       portable, since different machines use different argument passing  con-
       ventions.   Routines  with  variable arguments lists must use varargs()
       functions in order to run correctly on Sun-4 systems.

       va_alist() is used in a function header to declare a variable  argument
       list.

       va_dcl()  is  a declaration for va_alist().  No semicolon should follow
       va_dcl().

       va_list() is a type defined for the variable used to traverse the list.
       One such variable must always be declared.

       va_start(pvar)  is  called  to  initialize pvar to the beginning of the
       list.

       va_arg(pvar, type) will return the next argument in the list pointed to
       by  pvar.   The  parameter  type is a type name such that the type of a
       pointer to an object that has the specified type can be obtained simply
       by  appending  a  *  to  type.   If type disagrees with the type of the
       actual next argument (as promoted according  to  the  default  argument
       promotions), the behavior is undefined.

       In  standard  C,  arguments that are char or short are converted to int
       and should be accessed as int, arguments  that  are  unsigned  char  or
       unsigned  short are converted to unsigned int and should be accessed as
       unsigned int, and arguments that are float are converted to double  and
       should  be accessed as double.  Different types can be mixed, but it is
       up to the routine to know what type of argument is expected,  since  it
       cannot be determined at runtime.

       va_end(pvar) is used to finish up.

       Multiple  traversals,  each  bracketed by va_start() ...  va_end(), are
       possible.

       va_alist() must encompass the entire arguments list.  This insures that
       a #define statement can be used to redefine or expand its value.

       The  argument list (or its remainder) can be passed to another function
       using a pointer to a variable of type va_list() -- in which case a call
       to  va_arg()  in the subroutine advances the argument-list pointer with
       respect to the caller as well.

EXAMPLE
       This example is a possible implementation of execl(3V).
              #include <&lt;varargs.h>&gt;
              #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)
                        ;
                   va_end (ap);
                   return execv(file, args);
              }

SEE ALSO
       execl(3V), printf(3V)

BUGS
       It is up to the calling routine to specify  how  many  arguments  there
       are,  since  it is not possible to determine this from the stack frame.
       For example, execl() is passed a zero pointer to signal the end of  the
       list.  printf() can tell how many arguments are supposed to be there by
       the format.

       The macros va_start() and va_end()  may  be  arbitrarily  complex;  for
       example,  va_start() might contain an opening brace, which is closed by
       a matching brace in va_end().  Thus, they should  only  be  used  where
       they could be placed within a single complex statement.



                               19 December 1988                     VARARGS(3)