1VACALL(3) Library Functions Manual VACALL(3)
2
6 vacall - C functions called with variable arguments
7
9 #include <vacall.h>
10 extern void* vacall_function;
12 void function (va_alistalist)
14 {
15 va_start_type(alist[, return_type]);
16 arg = va_arg_type(alist[, arg_type]);
17 va_return_type(alist[[, return_type], return_value]);
18 }
19 vacall_function = &function;
21 val = ((return_type (*) ()) vacall) (arg1,arg2,...);
23
25 This set of macros permit a C function function to be called with vari‐
26 able arguments and to return variable return values. This is much like
27 the stdarg(3) facility, but also allows the return value to be speci‐
28 fied at run time.
29 Function calling conventions differ considerably on different machines,
31 and vacall attempts to provide some degree of isolation from such
32 architecture dependencies.
33 The function that can be called with any number and type of arguments
35 and which will return any type of return value is vacall. It will do
36 some magic and call the function stored in the variable vacall_func‐
37 tion. If you want to make more than one use of vacall, use the trampo‐
38 line(3) facility to store &function into vacall_function just before
39 calling vacall.
40 Within function, the following macros can be used to walk through the
42 argument list and specify a return value:
43 va_start_type(alist[, return_type]);
45 starts the walk through the argument list and specifies the
46 return type.
47 arg = va_arg_type(alist[, arg_type]);
49 fetches the next argument from the argument list.
50 va_return_type(alist[[, return_type], return_value]);
52 ends the walk through the argument list and specifies the return
53 value.
54 The type in va_start_type and va_return_type shall be one of void, int,
56 uint, long, ulong, longlong, ulonglong, double, struct, ptr or (for
57 ANSI C calling conventions only) char, schar, uchar, short, ushort,
58 float, depending on the class of return_type.
59 The type specifiers in va_start_type and va_return_type must be the
61 same. The return_type specifiers passed to va_start_type and
62 va_return_type must be the same.
63 The type in va_arg_type shall be one of int, uint, long, ulong, long‐
65 long, ulonglong, double, struct, ptr or (for ANSI C calling conventions
66 only) char, schar, uchar, short, ushort, float, depending on the class
67 of arg_type.
68 In va_start_struct(alist, return_type, splittable); the splittable flag
70 specifies whether the struct return_type can be returned in registers
71 such that every struct field fits entirely in a single register. This
72 needs to be specified for structs of size 2*sizeof(long). For structs
73 of size <= sizeof(long), splittable is ignored and assumed to be 1. For
74 structs of size > 2*sizeof(long), splittable is ignored and assumed to
75 be 0. There are some handy macros for this:
76 va_word_splittable_1 (type1)
77 va_word_splittable_2 (type1, type2)
78 va_word_splittable_3 (type1, type2, type3)
79 va_word_splittable_4 (type1, type2, type3, type4)
80 For a struct with three slots
81 struct { type1 id1; type2 id2; type3 id3; }
82 you can specify splittable as va_word_splittable_3 (type1, type2,
83 type3) .
84
87 Functions which want to emulate Kernighan & Ritchie style functions
88 (i.e., in ANSI C, functions without a typed argument list) cannot use
89 the type values char, schar, uchar, short, ushort, float. As pre‐
90 scribed by the default K&R C expression promotions, they have to use
91 int instead of char, schar, uchar, short, ushort and double instead of
92 float.
93 The macros va_start_longlong(), va_start_ulonglong(), va_return_long‐
95 long(), va_return_ulonglong(), va_arg_longlong() and va_arg_ulonglong()
96 work only if the C compiler has a working long long 64-bit integer
97 type.
98 The struct types used in va_start_struct() and va_struct() must only
100 contain (signed or unsigned) int, long, long long or pointer fields.
101 Struct types containing (signed or unsigned) char, short, float, double
102 or other structs are not supported.
103
106 This example, a possible implementation of execl(3) on top of execv(2)
107 using stdarg(3),
108 #include <stdarg.h>
110 #define MAXARGS 100
111 /* execl is called by execl(file, arg1, arg2, ..., (char *)0); */
112 int execl (...)
113 {
114 va_list ap;
115 char* file;
116 char* args[MAXARGS];
117 int argno = 0;
118 va_start (ap);
119 file = va_arg(ap, char*);
120 while ((args[argno] = va_arg(ap, char*)) != (char *)0)
121 argno++;
122 va_end (ap);
123 return execv(file, args);
124 }
125 looks like this using vacall(3):
127 #include <vacall.h>
129 #define MAXARGS 100
130 /* execl is called by vacall(file, arg1, arg2, ..., (char *)0); */
131 void execl (va_alist ap)
132 {
133 char* file;
134 char* args[MAXARGS];
135 int argno = 0;
136 int retval;
137 va_start_int (ap);
138 file = va_arg_ptr(ap, char*);
139 while ((args[argno] = va_arg_ptr(ap, char*)) != (char *)0)
140 argno++;
141 retval = execv(file, args);
142 va_return_int (ap, retval);
143 }
144 vacall_function = &execl;
145
148 stdarg(3), trampoline(3), callback(3).
149
152 The current implementations have been tested on a selection of common
153 cases but there are probably still many bugs.
154 There are typically built-in limits on the size of the argument-list,
156 which may also include the size of any structure arguments.
157 The decision whether a struct is to be returned in registers or in mem‐
159 ory considers only the struct's size and alignment. This is inaccurate:
160 for example, gcc on m68k-next returns struct { char a,b,c; } in regis‐
161 ters and struct { char a[3]; } in memory, although both types have the
162 same size and the same alignment.
163 The argument list can only be walked once.
165 The use of the global variable vacall_function is not reentrant. This
167 is fixed in the callback(3) package.
168
171 Knowledge about argument passing conventions can be found in the gcc
172 source, file gcc-2.6.3/config/cpu/cpu.h, section "Stack layout; func‐
173 tion entry, exit and calling."
174 The implementation of varargs for gcc can be found in the gcc source,
176 files gcc-2.6.3/ginclude/va*.h.
177 gcc's __builtin_saveregs() function is defined in the gcc source, file
179 gcc-2.6.3/libgcc2.c.
180
183 Bruno Haible <bruno@clisp.org>
184
187 Many ideas and a lot of code were cribbed from the gcc source.
188 1 January 2017 VACALL(3)