|
0
|
1 .\" Copyright (c) 2007-2013 Daniel Adler <dadler AT uni-goettingen DOT de>,
|
|
|
2 .\" Tassilo Philipp <tphilipp AT potion-studios DOT com>
|
|
|
3 .\"
|
|
|
4 .\" Permission to use, copy, modify, and distribute this software for any
|
|
|
5 .\" purpose with or without fee is hereby granted, provided that the above
|
|
|
6 .\" copyright notice and this permission notice appear in all copies.
|
|
|
7 .\"
|
|
|
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
|
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
|
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
|
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
|
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
|
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
|
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
|
15 .\"
|
|
|
16 .Dd $Mdocdate$
|
|
|
17 .Dt dyncall 3
|
|
|
18 .Os
|
|
|
19
|
|
|
20 .Sh NAME
|
|
|
21 .Nm dyncall
|
|
|
22 .Nd encapsulation of architecture-, OS- and compiler-specific function call
|
|
|
23 semantics
|
|
|
24 .Sh SYNOPSIS
|
|
|
25 .In dyncall.h
|
|
|
26 .Ft DCCallVM *
|
|
|
27 .Fn dcNewCallVM "DCsize size"
|
|
|
28 .Ft void
|
|
|
29 .Fn dcFree "DCCallVM * vm"
|
|
|
30 .Ft void
|
|
|
31 .Fn dcMode "DCCallVM * vm" "DCint mode"
|
|
|
32 .Ft void
|
|
|
33 .Fn dcReset "DCCallVM * vm"
|
|
|
34 .Ft void
|
|
|
35 .Fn dcArgBool "DCCallVM * vm" "DCbool arg"
|
|
|
36 .Ft void
|
|
|
37 .Fn dcArgChar "DCCallVM * vm" "DCchar arg"
|
|
|
38 .Ft void
|
|
|
39 .Fn dcArgShort "DCCallVM * vm" "DCshort arg"
|
|
|
40 .Ft void
|
|
|
41 .Fn dcArgInt "DCCallVM * vm" "DCint arg"
|
|
|
42 .Ft void
|
|
|
43 .Fn dcArgLong "DCCallVM * vm" "DClong arg"
|
|
|
44 .Ft void
|
|
|
45 .Fn dcArgLongLong "DCCallVM * vm" "DClonglong arg"
|
|
|
46 .Ft void
|
|
|
47 .Fn dcArgFloat "DCCallVM * vm" "DCfloat arg"
|
|
|
48 .Ft void
|
|
|
49 .Fn dcArgDouble "DCCallVM * vm" "DCdouble arg"
|
|
|
50 .Ft void
|
|
|
51 .Fn dcArgPointer "DCCallVM * vm" "DCpointer arg"
|
|
|
52 .Ft DCvoid
|
|
|
53 .Fn dcCallVoid "DCCallVM * vm" "DCpointer funcptr"
|
|
|
54 .Ft DCbool
|
|
|
55 .Fn dcCallBool "DCCallVM * vm" "DCpointer funcptr"
|
|
|
56 .Ft DCchar
|
|
|
57 .Fn dcCallChar "DCCallVM * vm" "DCpointer funcptr"
|
|
|
58 .Ft DCshort
|
|
|
59 .Fn dcCallShort "DCCallVM * vm" "DCpointer funcptr"
|
|
|
60 .Ft DCint
|
|
|
61 .Fn dcCallInt "DCCallVM * vm" "DCpointer funcptr"
|
|
|
62 .Ft DClong
|
|
|
63 .Fn dcCallLong "DCCallVM * vm" "DCpointer funcptr"
|
|
|
64 .Ft DClonglong
|
|
|
65 .Fn dcCallLongLong "DCCallVM * vm" "DCpointer funcptr"
|
|
|
66 .Ft DCfloat
|
|
|
67 .Fn dcCallFloat "DCCallVM * vm" "DCpointer funcptr"
|
|
|
68 .Ft DCdouble
|
|
|
69 .Fn dcCallDouble "DCCallVM * vm" "DCpointer funcptr"
|
|
|
70 .Ft DCpointer
|
|
|
71 .Fn dcCallPointer "DCCallVM * vm" "DCpointer funcptr"
|
|
|
72 .Ft void
|
|
|
73 .Fn dcArgF "DCCallVM * vm" "const DCsigchar * signature" "..."
|
|
|
74 .Ft void
|
|
|
75 .Fn dcVArgF "DCCallVM * vm" "const DCsigchar * signature" "va_list args"
|
|
|
76 .Ft void
|
|
|
77 .Fn dcCallF "DCCallVM * vm" "DCValue * result" "DCpointer funcptr" "const DCsigchar * signature" "..."
|
|
|
78 .Ft void
|
|
|
79 .Fn dcVCallF "DCCallVM * vm" "DCValue * result" "DCpointer funcptr" "const DCsigchar * signature" "va_list args"
|
|
|
80 .Sh DESCRIPTION
|
|
|
81 The
|
|
|
82 .Nm
|
|
|
83 library encapsulates architecture-, OS- and compiler-specific function call
|
|
|
84 semantics in a virtual "bind argument parameters from left to right and then
|
|
|
85 call" interface allowing programmers to call C functions in a completely
|
|
|
86 dynamic manner.
|
|
|
87 .Pp
|
|
|
88 In other words, instead of calling a function directly, the
|
|
|
89 .Nm
|
|
|
90 library provides a mechanism to push the function parameters manually and to
|
|
|
91 issue the call afterwards.
|
|
|
92 .Pp
|
|
|
93 Since the idea behind this concept is similar to call dispatching mechanisms
|
|
|
94 of virtual machines, the object that can be dynamically loaded with arguments,
|
|
|
95 and then used to actually invoke the call, is called CallVM. It is possible to
|
|
|
96 change the calling convention used by the CallVM at run-time. Due to the fact
|
|
|
97 that nearly every platform comes with one or more distinct calling conventions, the
|
|
|
98 .Nm
|
|
|
99 library project intends to be a portable and open-source approach to the variety of
|
|
|
100 compiler-specific binary interfaces, platform specific subtleties, and so on...
|
|
|
101 .Pp
|
|
|
102 .Fn dcNewCallVM
|
|
|
103 creates a new CallVM object, where
|
|
|
104 .Ar size
|
|
|
105 specifies the max size of the internal stack that will be allocated and used to
|
|
|
106 bind the arguments to. Use
|
|
|
107 .Fn dcFree
|
|
|
108 to destroy the CallVM object.
|
|
|
109 .Pp
|
|
|
110 .Fn dcMode
|
|
|
111 sets the calling convention to use. See dyncall.h for a list of
|
|
|
112 available modes. Note that some mode/platform combinations don't make any
|
|
|
113 sense (e.g. using a PowerPC calling convention on a MIPS platform) and are
|
|
|
114 silently ignored.
|
|
|
115 .Pp
|
|
|
116 .Fn dcReset
|
|
|
117 resets the internal stack of arguments and prepares it for the selected mode.
|
|
|
118 This function should be called after setting the call mode (using dcMode), but
|
|
|
119 prior to binding arguments to the CallVM. Use it also when reusing a CallVM, as
|
|
|
120 arguments don't get flushed automatically after a function call invocation.
|
|
|
121 .Pp
|
|
|
122 .Fn dcArgBool ,
|
|
|
123 .Fn dcArgChar ,
|
|
|
124 .Fn dcArgShort ,
|
|
|
125 .Fn dcArgInt ,
|
|
|
126 .Fn dcArgLong ,
|
|
|
127 .Fn dcArgLongLong ,
|
|
|
128 .Fn dcArgFloat ,
|
|
|
129 .Fn dcArgDouble
|
|
|
130 and
|
|
|
131 .Fn dcArgPointer
|
|
|
132 are used to bind arguments of the named types to the CallVM object. Arguments should
|
|
|
133 be bound in
|
|
|
134 .Em "left to right"
|
|
|
135 order regarding the C function prototype.
|
|
|
136 .Pp
|
|
|
137 .Fn dcCallVoid ,
|
|
|
138 .Fn dcCallBool ,
|
|
|
139 .Fn dcCallChar ,
|
|
|
140 .Fn dcCallShort ,
|
|
|
141 .Fn dcCallInt ,
|
|
|
142 .Fn dcCallLong ,
|
|
|
143 .Fn dcCallLongLong ,
|
|
|
144 .Fn dcCallFloat ,
|
|
|
145 .Fn dcCallDouble
|
|
|
146 and
|
|
|
147 .Fn dcCallPointer
|
|
|
148 call the function with the bound arguments and returning the named type, where
|
|
|
149 .Ar funcptr
|
|
|
150 is a pointer to the function to call. After the invocation of the function
|
|
|
151 call, the argument values are still bound to the CallVM and a second call
|
|
|
152 using the same arguments can be issued. Call
|
|
|
153 .Fn reset
|
|
|
154 to clear the internal argument stack.
|
|
|
155 .Pp
|
|
|
156 .Fn dcArgF ,
|
|
|
157 .Fn dcVArgF ,
|
|
|
158 .Fn dcCallF
|
|
|
159 and
|
|
|
160 .Fn dcVCallF
|
|
|
161 can be used to bind arguments in a printf-style call, using a signature
|
|
|
162 string encoding the argument types and return type. The former 2 only bind
|
|
|
163 the arguments to the
|
|
|
164 .Ar vm
|
|
|
165 object (and ignore return types specified in the
|
|
|
166 signature), whereas the latter two issue a call to the given function pointer,
|
|
|
167 afterwards. The return value will be stored in
|
|
|
168 .Ar result .
|
|
|
169 For information about the signature format, refer to the
|
|
|
170 .Nm
|
|
|
171 manual in PDF format.
|
|
|
172 .Sh EXAMPLE
|
|
|
173 Let's say, we want to make a call to the function:
|
|
|
174 .Bd -literal -offset indent
|
|
|
175 double sqrt(double x);
|
|
|
176 .Ed
|
|
|
177 .Pp
|
|
|
178 Using the
|
|
|
179 .Nm
|
|
|
180 library, this function would be called as follows:
|
|
|
181 .Bd -literal -offset indent
|
|
|
182 double r;
|
|
|
183 DCCallVM* vm = dcNewCallVM(4096);
|
|
|
184 dcMode(vm, DC_CALL_C_DEFAULT);
|
|
|
185 dcReset(vm);
|
|
|
186 dcArgDouble(vm, 4.2373);
|
|
|
187 r = dcCallDouble(vm, (DCpointer)&sqrt);
|
|
|
188 dcFree(vm);
|
|
|
189 .Ed
|
|
|
190 .Sh SEE ALSO
|
|
|
191 .Xr dyncallback 3 ,
|
|
|
192 .Xr dynload 3
|
|
|
193 and the
|
|
|
194 .Nm
|
|
|
195 manual (available in PDF format) for a way more detailed documentation of this
|
|
|
196 library.
|
|
|
197 .Sh AUTHORS
|
|
|
198 .An "Daniel Adler" Aq dadler@uni-goettingen.de
|
|
|
199 .An "Tassilo Philipp" Aq tphilipp@potion-studios.com
|
