VACALL(3)                 OpenBSD Programmer's Manual                VACALL(3)



NAME
       vacall - C functions called with variable arguments

SYNOPSIS
       #include <vacall.h>

       extern void* vacall_function;

       void function (alist)
         va_alist alist;
       {
         va_start_type(alist[, return_type]);
         arg = va_arg_type(alist[, arg_type]);
         va_return_type(alist[[, return_type], return_value]);
       }

       vacall_function = &function;

       val = ((return_type (*) ()) vacall) (arg1,arg2,...);

DESCRIPTION
       This set of macros permit a C function function to be called with
       variable arguments and to return variable return values.  This is much
       like the varargs(3) facility, but also allows the return value to be
       specified at run time.

       Function calling conventions differ considerably on different machines,
       and vacall attempts to provide some degree of isolation from such
       architecture dependencies.

       The function that can be called with any number and type of arguments
       and which will return any type of return value is vacall.  It will do
       some magic and call the function stored in the variable
       vacall_function.  If you want to make more than one use of vacall, use
       the trampoline(3) facility to store &function into vacall_function just
       before calling vacall.

       Within function, the following macros can be used to walk through the
       argument list and specify a return value:

       va_start_type(alist[, return_type]);
              starts the walk through the argument list and specifies the
              return type.

       arg = va_arg_type(alist[, arg_type]);
              fetches the next argument from the argument list.

       va_return_type(alist[[, return_type], return_value]);
              ends the walk through the argument list and specifies the return
              value.

       The type in va_start_type and va_return_type shall be one of void, int,
       uint, long, ulong, longlong, ulonglong, double, struct, ptr or (for
       ANSI C calling conventions only) char, schar, uchar, short, ushort,
       float, depending on the class of return_type.

       The type specifiers in va_start_type and va_return_type must be the
       same.  The return_type specifiers passed to va_start_type and
       va_return_type must be the same.

       The type in va_arg_type shall be one of int, uint, long, ulong,
       longlong, ulonglong, double, struct, ptr or (for ANSI C calling
       conventions only) char, schar, uchar, short, ushort, float, depending
       on the class of arg_type.

       In va_start_struct(alist, return_type, splittable); the splittable flag
       specifies whether the struct return_type can be returned in registers
       such that every struct field fits entirely in a single register. This
       needs to be specified for structs of size 2*sizeof(long). For structs
       of size <= sizeof(long), splittable is ignored and assumed to be 1. For
       structs of size > 2*sizeof(long), splittable is ignored and assumed to
       be 0. There are some handy macros for this:
       va_word_splittable_1 (type1)
       va_word_splittable_2 (type1, type2)
       va_word_splittable_3 (type1, type2, type3)
       va_word_splittable_4 (type1, type2, type3, type4)
       For a struct with three slots
       struct { type1 id1; type2 id2; type3 id3; }
       you can specify splittable as va_word_splittable_3 (type1, type2,
       type3) .


NOTES
       Functions which want to emulate Kernighan & Ritchie style functions
       (i.e., in ANSI C, functions without a typed argument list) cannot use
       the type values char, schar, uchar, short, ushort, float.  As
       prescribed by the default K&R C expression promotions, they have to use
       int instead of char, schar, uchar, short, ushort and double instead of
       float.

       The macros va_start_longlong(), va_start_ulonglong(),
       va_return_longlong(), va_return_ulonglong(), va_arg_longlong() and
       va_arg_ulonglong() work only if the C compiler has a working long long
       64-bit integer type.

       The struct types used in va_start_struct() and va_struct() must only
       contain (signed or unsigned) int, long, long long or pointer fields.
       Struct types containing (signed or unsigned) char, short, float, double
       or other structs are not supported.


EXAMPLE
       This example, a possible implementation of execl(3) on top of execv(2)
       using varargs(3),

       #include <varargs.h>
       #define MAXARGS 100
       /* execl is called by execl(file, arg1, arg2, ..., (char *)0); */
       int 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)
           argno++;
         va_end (ap);
         return execv(file, args);
       }

       looks like this using vacall(3):

       #include <vacall.h>
       #define MAXARGS 100
       /* execl is called by vacall(file, arg1, arg2, ..., (char *)0); */
       void execl (ap)
         va_alist ap;
       {
         char* file;
         char* args[MAXARGS];
         int argno = 0;
         int retval;
         va_start_int (ap);
         file = va_arg_ptr(ap, char*);
         while ((args[argno] = va_arg_ptr(ap, char*)) != (char *)0)
           argno++;
         retval = execv(file, args);
         va_return_int (ap, retval);
       }
       vacall_function = &execl;


SEE ALSO
       varargs(3), trampoline(3), callback(3).


BUGS
       The current implementations have been tested on a selection of common
       cases but there are probably still many bugs.

       There are typically built-in limits on the size of the argument-list,
       which may also include the size of any structure arguments.

       The decision whether a struct is to be returned in registers or in
       memory considers only the struct's size and alignment. This is
       inaccurate: for example, gcc on m68k-next returns struct { char a,b,c;
       } in registers and struct { char a[3]; } in memory, although both types
       have the same size and the same alignment.

       <vacall.h> cannot be included when <varargs.h> or <stdarg.h> is
       included.  (Name clash for va_alist.)

       The argument list can only be walked once.

       The use of the global variable vacall_function is not reentrant. This
       is fixed in the callback(3) package.


PORTING
       Knowledge about argument passing conventions can be found in the gcc
       source, file gcc-2.6.3/config/cpu/cpu.h, section "Stack layout;
       function entry, exit and calling."

       The implementation of varargs for gcc can be found in the gcc source,
       files gcc-2.6.3/ginclude/va*.h.

       gcc's __builtin_saveregs() function is defined in the gcc source, file
       gcc-2.6.3/libgcc2.c.


AUTHOR
       Bruno Haible <bruno@clisp.org>


ACKNOWLEDGEMENTS
       Many ideas and a lot of code were cribbed from the gcc source.




                                14 January 2001                      VACALL(3)
