Mercurial > pub > dyncall > dyncall

comparison dyncall/dyncall.3 @ 0:3e629dc19168

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial from svn dyncall-1745
author Daniel Adler
date Thu, 19 Mar 2015 22:24:28 +0100
parents
children 9bd3c5219505
comparison
equal deleted inserted replaced
-1:000000000000 0:3e629dc19168
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