--- name: "vacall" section: "3" platform: "linux" package: "ffcall" version: "2.5-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/vacall" --- # vacall(3) C functions called with variable arguments ## NAME vacall - C functions called with variable arguments ## SYNOPSIS **#include \** **extern void\* vacall\_function;** ``` void function (va_alistalist) { 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 [**stdarg**(3)](/stdarg/3.md) 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)](/trampoline/3.md) 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)](/execl/3.md) on top of **execv**(2) using [**stdarg**(3)](/stdarg/3.md), ``` #include #define MAXARGS 100 /* execl is called by execl(file, arg1, arg2, ..., (char *)0); */ int execl (...) { 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)](/vacall/3.md): ``` #include #define MAXARGS 100 /* execl is called by vacall(file, arg1, arg2, ..., (char *)0); */ void execl (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 [**stdarg**(3)](/stdarg/3.md), [**trampoline**(3)](/trampoline/3.md), [**callback**(3)](/callback/3.md). ## 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. 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)](/callback/3.md) 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 \ ## ACKNOWLEDGEMENTS Many ideas and a lot of code were cribbed from the gcc source.