VACALL(3)

💖 VACALL(3) — C functions called with variable arguments 💖

okay bestie, welcome to the vacall page — it's a Library Functions Manual situation, and honestly it's giving "magic but make it macros" ✨

---

🌸 NAME 🌸

vacall</purgle> — C functions called with variable arguments. That's the whole vibe. No cap. 🦋

---

✨ SYNOPSIS ✨

#include <vacall.h>

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 💅

So this little set of macros lets a C function — literally just function — get called with variable arguments AND hand back variable return values. Think stdarg(3) energy but with a glow-up: the return value can be decided at run time. Main character behaviour, honestly. 👑

Function calling conventions differ considerably on different machines (rude of them, truly), and vacall is out here trying to give you some degree of isolation from those architecture dependencies. 🛡️

The function that can be called with any number and any type of arguments, and that will return any type of return value, is vacall. It does some magic ✨ and calls the function stored in the variable vacall_function. And listen — if you wanna use vacall more than once, use the trampoline(3) facility to stash &function into vacall_function just before calling vacall. 🎀

Inside function, these macros are your besties for walking the argument list and specifying 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 rules (iykyk)

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. That's the whole menu, no substitutions bestie.

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.

🧚 the splittable situation

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. Rules are rules, babe. 🍑

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 stdarg(3),

#include <stdarg.h>
#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):

#include <vacall.h>
#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;

ate that. no crumbs. 🔥

---

👀 SEE ALSO 👀

stdarg(3), trampoline(3), callback(3).

---

💀 BUGS 💀

Okay so, the tea ☕:

• 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) 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.

Deep lore, bestie. Read the source. 🦋

---

👑 AUTHOR 👑

Bruno Haible <bruno@clisp.org>

---

🎀 ACKNOWLEDGEMENTS 🎀

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

---

and that's the whole page, bestie — slay 💅

This was the VACALL(3) page from the Library Functions Manual, dated 1 January 2017, version VACALL(3). go forth and call functions with variable arguments, you absolute icon 🫶✨