8
vacall - C functions called with variable arguments
11
##iinncclluuddee <<vvaaccaallll..hh>>
13
eexxtteerrnn vvooiidd** vvaaccaallll__ffuunnccttiioonn;;
15
vvooiidd _f_u_n_c_t_i_o_n ((_a_l_i_s_t))
16
vvaa__aalliisstt _a_l_i_s_t;;
18
vvaa__ssttaarrtt___t_y_p_e((_a_l_i_s_t[[,, _r_e_t_u_r_n___t_y_p_e]]));;
19
_a_r_g == vvaa__aarrgg___t_y_p_e((_a_l_i_s_t[[,, _a_r_g___t_y_p_e]]));;
20
vvaa__rreettuurrnn___t_y_p_e((_a_l_i_s_t[[[[,, _r_e_t_u_r_n___t_y_p_e]],, _r_e_t_u_r_n___v_a_l_u_e]]));;
23
vvaaccaallll__ffuunnccttiioonn == _&_f_u_n_c_t_i_o_n;;
25
_v_a_l == ((((_r_e_t_u_r_n___t_y_p_e ((**)) (()))) vvaaccaallll)) ((_a_r_g_1,,_a_r_g_2,,_._._.));;
27
DDEESSCCRRIIPPTTIIOONN
28
This set of macros permit a C function _f_u_n_c_t_i_o_n to be
29
called with variable arguments and to return variable
30
return values. This is much like the vvaarraarrggss(3) facility,
31
but also allows the return value to be specified at run
34
Function calling conventions differ considerably on dif-
35
ferent machines, and _v_a_c_a_l_l attempts to provide some
36
degree of isolation from such architecture dependencies.
38
The function that can be called with any number and type
39
of arguments and which will return any type of return
40
value is vvaaccaallll. It will do some magic and call the func-
41
tion stored in the variable vvaaccaallll__ffuunnccttiioonn. If you want
42
to make more than one use of _v_a_c_a_l_l, use the _t_r_a_m_p_o_l_i_n_e(3)
43
facility to store _&_f_u_n_c_t_i_o_n into vvaaccaallll__ffuunnccttiioonn just
44
before calling vvaaccaallll.
46
Within _f_u_n_c_t_i_o_n, the following macros can be used to walk
47
through the argument list and specify a return value:
49
vvaa__ssttaarrtt___t_y_p_e((_a_l_i_s_t[[,, _r_e_t_u_r_n___t_y_p_e]]));;
50
starts the walk through the argument list and spec-
51
ifies the return type.
53
_a_r_g == vvaa__aarrgg___t_y_p_e((_a_l_i_s_t[[,, _a_r_g___t_y_p_e]]));;
54
fetches the next argument from the argument list.
56
vvaa__rreettuurrnn___t_y_p_e((_a_l_i_s_t[[[[,, _r_e_t_u_r_n___t_y_p_e]],, _r_e_t_u_r_n___v_a_l_u_e]]));;
57
ends the walk through the argument list and speci-
58
fies the return value.
60
The _t_y_p_e in vvaa__ssttaarrtt___t_y_p_e and vvaa__rreettuurrnn___t_y_p_e shall be one
73
of vvooiidd, iinntt, uuiinntt, lloonngg, uulloonngg, lloonngglloonngg, uulloonngglloonngg, ddoouu--
74
bbllee, ssttrruucctt, ppttrr or (for ANSI C calling conventions only)
75
cchhaarr, sscchhaarr, uucchhaarr, sshhoorrtt, uusshhoorrtt, ffllooaatt, depending on the
76
class of _r_e_t_u_r_n___t_y_p_e.
78
The _t_y_p_e specifiers in vvaa__ssttaarrtt___t_y_p_e and vvaa__rreettuurrnn___t_y_p_e
79
must be the same. The _r_e_t_u_r_n___t_y_p_e specifiers passed to
80
vvaa__ssttaarrtt___t_y_p_e and vvaa__rreettuurrnn___t_y_p_e must be the same.
82
The _t_y_p_e in vvaa__aarrgg___t_y_p_e shall be one of iinntt, uuiinntt, lloonngg,
83
uulloonngg, lloonngglloonngg, uulloonngglloonngg, ddoouubbllee, ssttrruucctt, ppttrr or (for
84
ANSI C calling conventions only) cchhaarr, sscchhaarr, uucchhaarr,
85
sshhoorrtt, uusshhoorrtt, ffllooaatt, depending on the class of _a_r_g___t_y_p_e.
87
In vvaa__ssttaarrtt__ssttrruucctt((_a_l_i_s_t,, _r_e_t_u_r_n___t_y_p_e,, _s_p_l_i_t_t_a_b_l_e));; the
88
_s_p_l_i_t_t_a_b_l_e flag specifies whether the struct _r_e_t_u_r_n___t_y_p_e
89
can be returned in registers such that every struct field
90
fits entirely in a single register. This needs to be spec-
91
ified for structs of size 2*sizeof(long). For structs of
92
size <= sizeof(long), _s_p_l_i_t_t_a_b_l_e is ignored and assumed to
93
be 1. For structs of size > 2*sizeof(long), _s_p_l_i_t_t_a_b_l_e is
94
ignored and assumed to be 0. There are some handy macros
96
vvaa__wwoorrdd__sspplliittttaabbllee__11 ((_t_y_p_e_1))
97
vvaa__wwoorrdd__sspplliittttaabbllee__22 ((_t_y_p_e_1,, _t_y_p_e_2))
98
vvaa__wwoorrdd__sspplliittttaabbllee__33 ((_t_y_p_e_1,, _t_y_p_e_2,, _t_y_p_e_3))
99
vvaa__wwoorrdd__sspplliittttaabbllee__44 ((_t_y_p_e_1,, _t_y_p_e_2,, _t_y_p_e_3,, _t_y_p_e_4))
100
For a struct with three slots
101
ssttrruucctt {{ _t_y_p_e_1 _i_d_1;; _t_y_p_e_2 _i_d_2;; _t_y_p_e_3 _i_d_3;; }}
102
you can specify _s_p_l_i_t_t_a_b_l_e as vvaa__wwoorrdd__sspplliittttaabbllee__33 ((_t_y_p_e_1,,
103
_t_y_p_e_2,, _t_y_p_e_3)) .
107
Functions which want to emulate Kernighan & Ritchie style
108
functions (i.e., in ANSI C, functions without a typed
109
argument list) cannot use the _t_y_p_e values cchhaarr, sscchhaarr,
110
uucchhaarr, sshhoorrtt, uusshhoorrtt, ffllooaatt. As prescribed by the default
111
K&R C expression promotions, they have to use iinntt instead
112
of cchhaarr, sscchhaarr, uucchhaarr, sshhoorrtt, uusshhoorrtt and ddoouubbllee instead of
115
The macros vvaa__ssttaarrtt__lloonngglloonngg(()), vvaa__ssttaarrtt__uulloonngglloonngg(()),
116
vvaa__rreettuurrnn__lloonngglloonngg(()), vvaa__rreettuurrnn__uulloonngglloonngg(()),
117
vvaa__aarrgg__lloonngglloonngg(()) and vvaa__aarrgg__uulloonngglloonngg(()) work only if the
118
C compiler has a working lloonngg lloonngg 64-bit integer type.
120
The struct types used in vvaa__ssttaarrtt__ssttrruucctt(()) and vvaa__ssttrruucctt(())
121
must only contain (signed or unsigned) int, long, long
122
long or pointer fields. Struct types containing (signed
123
or unsigned) char, short, float, double or other structs
140
This example, a possible implementation of eexxeeccll(3) on top
141
of eexxeeccvv(2) using vvaarraarrggss(3),
143
##iinncclluuddee <<vvaarraarrggss..hh>>
144
##ddeeffiinnee MMAAXXAARRGGSS 110000
145
//** eexxeeccll iiss ccaalllleedd bbyy eexxeeccll((ffiillee,, aarrgg11,, aarrgg22,, ......,, ((cchhaarr **))00));; **//
146
iinntt eexxeeccll ((vvaa__aalliisstt))
149
vvaa__lliisstt aapp;;
150
cchhaarr** ffiillee;;
151
cchhaarr** aarrggss[[MMAAXXAARRGGSS]];;
152
iinntt aarrggnnoo == 00;;
153
vvaa__ssttaarrtt ((aapp));;
154
ffiillee == vvaa__aarrgg((aapp,, cchhaarr**));;
155
wwhhiillee ((((aarrggss[[aarrggnnoo]] == vvaa__aarrgg((aapp,, cchhaarr**)))) !!== ((cchhaarr **))00))
157
vvaa__eenndd ((aapp));;
158
rreettuurrnn eexxeeccvv((ffiillee,, aarrggss));;
161
looks like this using vvaaccaallll(3):
163
##iinncclluuddee <<vvaaccaallll..hh>>
164
##ddeeffiinnee MMAAXXAARRGGSS 110000
165
//** eexxeeccll iiss ccaalllleedd bbyy vvaaccaallll((ffiillee,, aarrgg11,, aarrgg22,, ......,, ((cchhaarr **))00));; **//
166
vvooiidd eexxeeccll ((aapp))
167
vvaa__aalliisstt aapp;;
169
cchhaarr** ffiillee;;
170
cchhaarr** aarrggss[[MMAAXXAARRGGSS]];;
171
iinntt aarrggnnoo == 00;;
172
iinntt rreettvvaall;;
173
vvaa__ssttaarrtt__iinntt ((aapp));;
174
ffiillee == vvaa__aarrgg__ppttrr((aapp,, cchhaarr**));;
175
wwhhiillee ((((aarrggss[[aarrggnnoo]] == vvaa__aarrgg__ppttrr((aapp,, cchhaarr**)))) !!== ((cchhaarr **))00))
177
rreettvvaall == eexxeeccvv((ffiillee,, aarrggss));;
178
vvaa__rreettuurrnn__iinntt ((aapp,, rreettvvaall));;
180
vvaaccaallll__ffuunnccttiioonn == &&eexxeeccll;;
184
vvaarraarrggss(3), ttrraammppoolliinnee(3), ccaallllbbaacckk(3).
188
The current implementations have been tested on a selec-
189
tion of common cases but there are probably still many
192
There are typically built-in limits on the size of the
205
argument-list, which may also include the size of any
208
The decision whether a struct is to be returned in regis-
209
ters or in memory considers only the struct's size and
210
alignment. This is inaccurate: for example, gcc on m68k-
211
next returns ssttrruucctt {{ cchhaarr aa,,bb,,cc;; }} in registers and
212
ssttrruucctt {{ cchhaarr aa[[33]];; }} in memory, although both types have
213
the same size and the same alignment.
215
<<vvaaccaallll..hh>> cannot be included when <<vvaarraarrggss..hh>> or
216
<<ssttddaarrgg..hh>> is included. (Name clash for vvaa__aalliisstt.)
218
The argument list can only be walked once.
220
The use of the global variable vvaaccaallll__ffuunnccttiioonn is not
221
reentrant. This is fixed in the ccaallllbbaacckk(3) package.
225
Knowledge about argument passing conventions can be found
226
in the gcc source, file gcc-2.6.3/config/_c_p_u/_c_p_u.h, sec-
227
tion "Stack layout; function entry, exit and calling."
229
The implementation of varargs for gcc can be found in the
230
gcc source, files gcc-2.6.3/ginclude/va*.h.
232
gcc's __builtin_saveregs() function is defined in the gcc
233
source, file gcc-2.6.3/libgcc2.c.
237
Bruno Haible <bruno@clisp.org>
240
AACCKKNNOOWWLLEEDDGGEEMMEENNTTSS
241
Many ideas and a lot of code were cribbed from the gcc