|
111
|
1 \input texinfo @c -*-texinfo-*-
|
|
|
2 @c %**start of header
|
|
|
3 @setfilename libffi.info
|
|
|
4 @settitle libffi
|
|
|
5 @setchapternewpage off
|
|
|
6 @c %**end of header
|
|
|
7
|
|
|
8 @c Merge the standard indexes into a single one.
|
|
|
9 @syncodeindex fn cp
|
|
|
10 @syncodeindex vr cp
|
|
|
11 @syncodeindex ky cp
|
|
|
12 @syncodeindex pg cp
|
|
|
13 @syncodeindex tp cp
|
|
|
14
|
|
|
15 @include version.texi
|
|
|
16
|
|
|
17 @copying
|
|
|
18
|
|
|
19 This manual is for Libffi, a portable foreign-function interface
|
|
|
20 library.
|
|
|
21
|
|
|
22 Copyright @copyright{} 2008, 2010, 2011 Red Hat, Inc.
|
|
|
23
|
|
|
24 @quotation
|
|
|
25 Permission is granted to copy, distribute and/or modify this document
|
|
|
26 under the terms of the GNU General Public License as published by the
|
|
|
27 Free Software Foundation; either version 2, or (at your option) any
|
|
|
28 later version. A copy of the license is included in the
|
|
|
29 section entitled ``GNU General Public License''.
|
|
|
30
|
|
|
31 @end quotation
|
|
|
32 @end copying
|
|
|
33
|
|
|
34 @dircategory Development
|
|
|
35 @direntry
|
|
|
36 * libffi: (libffi). Portable foreign-function interface library.
|
|
|
37 @end direntry
|
|
|
38
|
|
|
39 @titlepage
|
|
|
40 @title Libffi
|
|
|
41 @page
|
|
|
42 @vskip 0pt plus 1filll
|
|
|
43 @insertcopying
|
|
|
44 @end titlepage
|
|
|
45
|
|
|
46
|
|
|
47 @ifnottex
|
|
|
48 @node Top
|
|
|
49 @top libffi
|
|
|
50
|
|
|
51 @insertcopying
|
|
|
52
|
|
|
53 @menu
|
|
|
54 * Introduction:: What is libffi?
|
|
|
55 * Using libffi:: How to use libffi.
|
|
|
56 * Missing Features:: Things libffi can't do.
|
|
|
57 * Index:: Index.
|
|
|
58 @end menu
|
|
|
59
|
|
|
60 @end ifnottex
|
|
|
61
|
|
|
62
|
|
|
63 @node Introduction
|
|
|
64 @chapter What is libffi?
|
|
|
65
|
|
|
66 Compilers for high level languages generate code that follow certain
|
|
|
67 conventions. These conventions are necessary, in part, for separate
|
|
|
68 compilation to work. One such convention is the @dfn{calling
|
|
|
69 convention}. The calling convention is a set of assumptions made by
|
|
|
70 the compiler about where function arguments will be found on entry to
|
|
|
71 a function. A calling convention also specifies where the return
|
|
|
72 value for a function is found. The calling convention is also
|
|
|
73 sometimes called the @dfn{ABI} or @dfn{Application Binary Interface}.
|
|
|
74 @cindex calling convention
|
|
|
75 @cindex ABI
|
|
|
76 @cindex Application Binary Interface
|
|
|
77
|
|
|
78 Some programs may not know at the time of compilation what arguments
|
|
|
79 are to be passed to a function. For instance, an interpreter may be
|
|
|
80 told at run-time about the number and types of arguments used to call
|
|
|
81 a given function. @samp{Libffi} can be used in such programs to
|
|
|
82 provide a bridge from the interpreter program to compiled code.
|
|
|
83
|
|
|
84 The @samp{libffi} library provides a portable, high level programming
|
|
|
85 interface to various calling conventions. This allows a programmer to
|
|
|
86 call any function specified by a call interface description at run
|
|
|
87 time.
|
|
|
88
|
|
|
89 @acronym{FFI} stands for Foreign Function Interface. A foreign
|
|
|
90 function interface is the popular name for the interface that allows
|
|
|
91 code written in one language to call code written in another language.
|
|
|
92 The @samp{libffi} library really only provides the lowest, machine
|
|
|
93 dependent layer of a fully featured foreign function interface. A
|
|
|
94 layer must exist above @samp{libffi} that handles type conversions for
|
|
|
95 values passed between the two languages.
|
|
|
96 @cindex FFI
|
|
|
97 @cindex Foreign Function Interface
|
|
|
98
|
|
|
99
|
|
|
100 @node Using libffi
|
|
|
101 @chapter Using libffi
|
|
|
102
|
|
|
103 @menu
|
|
|
104 * The Basics:: The basic libffi API.
|
|
|
105 * Simple Example:: A simple example.
|
|
|
106 * Types:: libffi type descriptions.
|
|
|
107 * Multiple ABIs:: Different passing styles on one platform.
|
|
|
108 * The Closure API:: Writing a generic function.
|
|
|
109 * Closure Example:: A closure example.
|
|
|
110 @end menu
|
|
|
111
|
|
|
112
|
|
|
113 @node The Basics
|
|
|
114 @section The Basics
|
|
|
115
|
|
|
116 @samp{Libffi} assumes that you have a pointer to the function you wish
|
|
|
117 to call and that you know the number and types of arguments to pass
|
|
|
118 it, as well as the return type of the function.
|
|
|
119
|
|
|
120 The first thing you must do is create an @code{ffi_cif} object that
|
|
|
121 matches the signature of the function you wish to call. This is a
|
|
|
122 separate step because it is common to make multiple calls using a
|
|
|
123 single @code{ffi_cif}. The @dfn{cif} in @code{ffi_cif} stands for
|
|
|
124 Call InterFace. To prepare a call interface object, use the function
|
|
|
125 @code{ffi_prep_cif}.
|
|
|
126 @cindex cif
|
|
|
127
|
|
|
128 @findex ffi_prep_cif
|
|
|
129 @defun ffi_status ffi_prep_cif (ffi_cif *@var{cif}, ffi_abi @var{abi}, unsigned int @var{nargs}, ffi_type *@var{rtype}, ffi_type **@var{argtypes})
|
|
|
130 This initializes @var{cif} according to the given parameters.
|
|
|
131
|
|
|
132 @var{abi} is the ABI to use; normally @code{FFI_DEFAULT_ABI} is what
|
|
|
133 you want. @ref{Multiple ABIs} for more information.
|
|
|
134
|
|
|
135 @var{nargs} is the number of arguments that this function accepts.
|
|
|
136
|
|
|
137 @var{rtype} is a pointer to an @code{ffi_type} structure that
|
|
|
138 describes the return type of the function. @xref{Types}.
|
|
|
139
|
|
|
140 @var{argtypes} is a vector of @code{ffi_type} pointers.
|
|
|
141 @var{argtypes} must have @var{nargs} elements. If @var{nargs} is 0,
|
|
|
142 this argument is ignored.
|
|
|
143
|
|
|
144 @code{ffi_prep_cif} returns a @code{libffi} status code, of type
|
|
|
145 @code{ffi_status}. This will be either @code{FFI_OK} if everything
|
|
|
146 worked properly; @code{FFI_BAD_TYPEDEF} if one of the @code{ffi_type}
|
|
|
147 objects is incorrect; or @code{FFI_BAD_ABI} if the @var{abi} parameter
|
|
|
148 is invalid.
|
|
|
149 @end defun
|
|
|
150
|
|
|
151 If the function being called is variadic (varargs) then
|
|
|
152 @code{ffi_prep_cif_var} must be used instead of @code{ffi_prep_cif}.
|
|
|
153
|
|
|
154 @findex ffi_prep_cif_var
|
|
|
155 @defun ffi_status ffi_prep_cif_var (ffi_cif *@var{cif}, ffi_abi var{abi}, unsigned int @var{nfixedargs}, unsigned int var{ntotalargs}, ffi_type *@var{rtype}, ffi_type **@var{argtypes})
|
|
|
156 This initializes @var{cif} according to the given parameters for
|
|
|
157 a call to a variadic function. In general it's operation is the
|
|
|
158 same as for @code{ffi_prep_cif} except that:
|
|
|
159
|
|
|
160 @var{nfixedargs} is the number of fixed arguments, prior to any
|
|
|
161 variadic arguments. It must be greater than zero.
|
|
|
162
|
|
|
163 @var{ntotalargs} the total number of arguments, including variadic
|
|
|
164 and fixed arguments.
|
|
|
165
|
|
|
166 Note that, different cif's must be prepped for calls to the same
|
|
|
167 function when different numbers of arguments are passed.
|
|
|
168
|
|
|
169 Also note that a call to @code{ffi_prep_cif_var} with
|
|
|
170 @var{nfixedargs}=@var{nototalargs} is NOT equivalent to a call to
|
|
|
171 @code{ffi_prep_cif}.
|
|
|
172
|
|
|
173 @end defun
|
|
|
174
|
|
|
175
|
|
|
176 To call a function using an initialized @code{ffi_cif}, use the
|
|
|
177 @code{ffi_call} function:
|
|
|
178
|
|
|
179 @findex ffi_call
|
|
|
180 @defun void ffi_call (ffi_cif *@var{cif}, void *@var{fn}, void *@var{rvalue}, void **@var{avalues})
|
|
|
181 This calls the function @var{fn} according to the description given in
|
|
|
182 @var{cif}. @var{cif} must have already been prepared using
|
|
|
183 @code{ffi_prep_cif}.
|
|
|
184
|
|
|
185 @var{rvalue} is a pointer to a chunk of memory that will hold the
|
|
|
186 result of the function call. This must be large enough to hold the
|
|
|
187 result, no smaller than the system register size (generally 32 or 64
|
|
|
188 bits), and must be suitably aligned; it is the caller's responsibility
|
|
|
189 to ensure this. If @var{cif} declares that the function returns
|
|
|
190 @code{void} (using @code{ffi_type_void}), then @var{rvalue} is
|
|
|
191 ignored.
|
|
|
192
|
|
|
193 @var{avalues} is a vector of @code{void *} pointers that point to the
|
|
|
194 memory locations holding the argument values for a call. If @var{cif}
|
|
|
195 declares that the function has no arguments (i.e., @var{nargs} was 0),
|
|
|
196 then @var{avalues} is ignored. Note that argument values may be
|
|
|
197 modified by the callee (for instance, structs passed by value); the
|
|
|
198 burden of copying pass-by-value arguments is placed on the caller.
|
|
|
199 @end defun
|
|
|
200
|
|
|
201
|
|
|
202 @node Simple Example
|
|
|
203 @section Simple Example
|
|
|
204
|
|
|
205 Here is a trivial example that calls @code{puts} a few times.
|
|
|
206
|
|
|
207 @example
|
|
|
208 #include <stdio.h>
|
|
|
209 #include <ffi.h>
|
|
|
210
|
|
|
211 int main()
|
|
|
212 @{
|
|
|
213 ffi_cif cif;
|
|
|
214 ffi_type *args[1];
|
|
|
215 void *values[1];
|
|
|
216 char *s;
|
|
|
217 ffi_arg rc;
|
|
|
218
|
|
|
219 /* Initialize the argument info vectors */
|
|
|
220 args[0] = &ffi_type_pointer;
|
|
|
221 values[0] = &s;
|
|
|
222
|
|
|
223 /* Initialize the cif */
|
|
|
224 if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
|
|
|
225 &ffi_type_sint, args) == FFI_OK)
|
|
|
226 @{
|
|
|
227 s = "Hello World!";
|
|
|
228 ffi_call(&cif, puts, &rc, values);
|
|
|
229 /* rc now holds the result of the call to puts */
|
|
|
230
|
|
|
231 /* values holds a pointer to the function's arg, so to
|
|
|
232 call puts() again all we need to do is change the
|
|
|
233 value of s */
|
|
|
234 s = "This is cool!";
|
|
|
235 ffi_call(&cif, puts, &rc, values);
|
|
|
236 @}
|
|
|
237
|
|
|
238 return 0;
|
|
|
239 @}
|
|
|
240 @end example
|
|
|
241
|
|
|
242
|
|
|
243 @node Types
|
|
|
244 @section Types
|
|
|
245
|
|
|
246 @menu
|
|
|
247 * Primitive Types:: Built-in types.
|
|
|
248 * Structures:: Structure types.
|
|
|
249 * Type Example:: Structure type example.
|
|
|
250 * Complex:: Complex types.
|
|
|
251 * Complex Type Example:: Complex type example.
|
|
|
252 @end menu
|
|
|
253
|
|
|
254 @node Primitive Types
|
|
|
255 @subsection Primitive Types
|
|
|
256
|
|
|
257 @code{Libffi} provides a number of built-in type descriptors that can
|
|
|
258 be used to describe argument and return types:
|
|
|
259
|
|
|
260 @table @code
|
|
|
261 @item ffi_type_void
|
|
|
262 @tindex ffi_type_void
|
|
|
263 The type @code{void}. This cannot be used for argument types, only
|
|
|
264 for return values.
|
|
|
265
|
|
|
266 @item ffi_type_uint8
|
|
|
267 @tindex ffi_type_uint8
|
|
|
268 An unsigned, 8-bit integer type.
|
|
|
269
|
|
|
270 @item ffi_type_sint8
|
|
|
271 @tindex ffi_type_sint8
|
|
|
272 A signed, 8-bit integer type.
|
|
|
273
|
|
|
274 @item ffi_type_uint16
|
|
|
275 @tindex ffi_type_uint16
|
|
|
276 An unsigned, 16-bit integer type.
|
|
|
277
|
|
|
278 @item ffi_type_sint16
|
|
|
279 @tindex ffi_type_sint16
|
|
|
280 A signed, 16-bit integer type.
|
|
|
281
|
|
|
282 @item ffi_type_uint32
|
|
|
283 @tindex ffi_type_uint32
|
|
|
284 An unsigned, 32-bit integer type.
|
|
|
285
|
|
|
286 @item ffi_type_sint32
|
|
|
287 @tindex ffi_type_sint32
|
|
|
288 A signed, 32-bit integer type.
|
|
|
289
|
|
|
290 @item ffi_type_uint64
|
|
|
291 @tindex ffi_type_uint64
|
|
|
292 An unsigned, 64-bit integer type.
|
|
|
293
|
|
|
294 @item ffi_type_sint64
|
|
|
295 @tindex ffi_type_sint64
|
|
|
296 A signed, 64-bit integer type.
|
|
|
297
|
|
|
298 @item ffi_type_float
|
|
|
299 @tindex ffi_type_float
|
|
|
300 The C @code{float} type.
|
|
|
301
|
|
|
302 @item ffi_type_double
|
|
|
303 @tindex ffi_type_double
|
|
|
304 The C @code{double} type.
|
|
|
305
|
|
|
306 @item ffi_type_uchar
|
|
|
307 @tindex ffi_type_uchar
|
|
|
308 The C @code{unsigned char} type.
|
|
|
309
|
|
|
310 @item ffi_type_schar
|
|
|
311 @tindex ffi_type_schar
|
|
|
312 The C @code{signed char} type. (Note that there is not an exact
|
|
|
313 equivalent to the C @code{char} type in @code{libffi}; ordinarily you
|
|
|
314 should either use @code{ffi_type_schar} or @code{ffi_type_uchar}
|
|
|
315 depending on whether @code{char} is signed.)
|
|
|
316
|
|
|
317 @item ffi_type_ushort
|
|
|
318 @tindex ffi_type_ushort
|
|
|
319 The C @code{unsigned short} type.
|
|
|
320
|
|
|
321 @item ffi_type_sshort
|
|
|
322 @tindex ffi_type_sshort
|
|
|
323 The C @code{short} type.
|
|
|
324
|
|
|
325 @item ffi_type_uint
|
|
|
326 @tindex ffi_type_uint
|
|
|
327 The C @code{unsigned int} type.
|
|
|
328
|
|
|
329 @item ffi_type_sint
|
|
|
330 @tindex ffi_type_sint
|
|
|
331 The C @code{int} type.
|
|
|
332
|
|
|
333 @item ffi_type_ulong
|
|
|
334 @tindex ffi_type_ulong
|
|
|
335 The C @code{unsigned long} type.
|
|
|
336
|
|
|
337 @item ffi_type_slong
|
|
|
338 @tindex ffi_type_slong
|
|
|
339 The C @code{long} type.
|
|
|
340
|
|
|
341 @item ffi_type_longdouble
|
|
|
342 @tindex ffi_type_longdouble
|
|
|
343 On platforms that have a C @code{long double} type, this is defined.
|
|
|
344 On other platforms, it is not.
|
|
|
345
|
|
|
346 @item ffi_type_pointer
|
|
|
347 @tindex ffi_type_pointer
|
|
|
348 A generic @code{void *} pointer. You should use this for all
|
|
|
349 pointers, regardless of their real type.
|
|
|
350
|
|
|
351 @item ffi_type_complex_float
|
|
|
352 @tindex ffi_type_complex_float
|
|
|
353 The C @code{_Complex float} type.
|
|
|
354
|
|
|
355 @item ffi_type_complex_double
|
|
|
356 @tindex ffi_type_complex_double
|
|
|
357 The C @code{_Complex double} type.
|
|
|
358
|
|
|
359 @item ffi_type_complex_longdouble
|
|
|
360 @tindex ffi_type_complex_longdouble
|
|
|
361 The C @code{_Complex long double} type.
|
|
|
362 On platforms that have a C @code{long double} type, this is defined.
|
|
|
363 On other platforms, it is not.
|
|
|
364 @end table
|
|
|
365
|
|
|
366 Each of these is of type @code{ffi_type}, so you must take the address
|
|
|
367 when passing to @code{ffi_prep_cif}.
|
|
|
368
|
|
|
369
|
|
|
370 @node Structures
|
|
|
371 @subsection Structures
|
|
|
372
|
|
|
373 Although @samp{libffi} has no special support for unions or
|
|
|
374 bit-fields, it is perfectly happy passing structures back and forth.
|
|
|
375 You must first describe the structure to @samp{libffi} by creating a
|
|
|
376 new @code{ffi_type} object for it.
|
|
|
377
|
|
|
378 @tindex ffi_type
|
|
|
379 @deftp {Data type} ffi_type
|
|
|
380 The @code{ffi_type} has the following members:
|
|
|
381 @table @code
|
|
|
382 @item size_t size
|
|
|
383 This is set by @code{libffi}; you should initialize it to zero.
|
|
|
384
|
|
|
385 @item unsigned short alignment
|
|
|
386 This is set by @code{libffi}; you should initialize it to zero.
|
|
|
387
|
|
|
388 @item unsigned short type
|
|
|
389 For a structure, this should be set to @code{FFI_TYPE_STRUCT}.
|
|
|
390
|
|
|
391 @item ffi_type **elements
|
|
|
392 This is a @samp{NULL}-terminated array of pointers to @code{ffi_type}
|
|
|
393 objects. There is one element per field of the struct.
|
|
|
394 @end table
|
|
|
395 @end deftp
|
|
|
396
|
|
|
397
|
|
|
398 @node Type Example
|
|
|
399 @subsection Type Example
|
|
|
400
|
|
|
401 The following example initializes a @code{ffi_type} object
|
|
|
402 representing the @code{tm} struct from Linux's @file{time.h}.
|
|
|
403
|
|
|
404 Here is how the struct is defined:
|
|
|
405
|
|
|
406 @example
|
|
|
407 struct tm @{
|
|
|
408 int tm_sec;
|
|
|
409 int tm_min;
|
|
|
410 int tm_hour;
|
|
|
411 int tm_mday;
|
|
|
412 int tm_mon;
|
|
|
413 int tm_year;
|
|
|
414 int tm_wday;
|
|
|
415 int tm_yday;
|
|
|
416 int tm_isdst;
|
|
|
417 /* Those are for future use. */
|
|
|
418 long int __tm_gmtoff__;
|
|
|
419 __const char *__tm_zone__;
|
|
|
420 @};
|
|
|
421 @end example
|
|
|
422
|
|
|
423 Here is the corresponding code to describe this struct to
|
|
|
424 @code{libffi}:
|
|
|
425
|
|
|
426 @example
|
|
|
427 @{
|
|
|
428 ffi_type tm_type;
|
|
|
429 ffi_type *tm_type_elements[12];
|
|
|
430 int i;
|
|
|
431
|
|
|
432 tm_type.size = tm_type.alignment = 0;
|
|
|
433 tm_type.type = FFI_TYPE_STRUCT;
|
|
|
434 tm_type.elements = &tm_type_elements;
|
|
|
435
|
|
|
436 for (i = 0; i < 9; i++)
|
|
|
437 tm_type_elements[i] = &ffi_type_sint;
|
|
|
438
|
|
|
439 tm_type_elements[9] = &ffi_type_slong;
|
|
|
440 tm_type_elements[10] = &ffi_type_pointer;
|
|
|
441 tm_type_elements[11] = NULL;
|
|
|
442
|
|
|
443 /* tm_type can now be used to represent tm argument types and
|
|
|
444 return types for ffi_prep_cif() */
|
|
|
445 @}
|
|
|
446 @end example
|
|
|
447
|
|
|
448 @node Complex
|
|
|
449 @subsection Complex Types
|
|
|
450
|
|
|
451 @samp{libffi} supports the complex types defined by the C99
|
|
|
452 standard (@code{_Complex float}, @code{_Complex double} and
|
|
|
453 @code{_Complex long double} with the built-in type descriptors
|
|
|
454 @code{ffi_type_complex_float}, @code{ffi_type_complex_double} and
|
|
|
455 @code{ffi_type_complex_longdouble}.
|
|
|
456
|
|
|
457 Custom complex types like @code{_Complex int} can also be used.
|
|
|
458 An @code{ffi_type} object has to be defined to describe the
|
|
|
459 complex type to @samp{libffi}.
|
|
|
460
|
|
|
461 @tindex ffi_type
|
|
|
462 @deftp {Data type} ffi_type
|
|
|
463 @table @code
|
|
|
464 @item size_t size
|
|
|
465 This must be manually set to the size of the complex type.
|
|
|
466
|
|
|
467 @item unsigned short alignment
|
|
|
468 This must be manually set to the alignment of the complex type.
|
|
|
469
|
|
|
470 @item unsigned short type
|
|
|
471 For a complex type, this must be set to @code{FFI_TYPE_COMPLEX}.
|
|
|
472
|
|
|
473 @item ffi_type **elements
|
|
|
474
|
|
|
475 This is a @samp{NULL}-terminated array of pointers to
|
|
|
476 @code{ffi_type} objects. The first element is set to the
|
|
|
477 @code{ffi_type} of the complex's base type. The second element
|
|
|
478 must be set to @code{NULL}.
|
|
|
479 @end table
|
|
|
480 @end deftp
|
|
|
481
|
|
|
482 The section @ref{Complex Type Example} shows a way to determine
|
|
|
483 the @code{size} and @code{alignment} members in a platform
|
|
|
484 independent way.
|
|
|
485
|
|
|
486 For platforms that have no complex support in @code{libffi} yet,
|
|
|
487 the functions @code{ffi_prep_cif} and @code{ffi_prep_args} abort
|
|
|
488 the program if they encounter a complex type.
|
|
|
489
|
|
|
490 @node Complex Type Example
|
|
|
491 @subsection Complex Type Example
|
|
|
492
|
|
|
493 This example demonstrates how to use complex types:
|
|
|
494
|
|
|
495 @example
|
|
|
496 #include <stdio.h>
|
|
|
497 #include <ffi.h>
|
|
|
498 #include <complex.h>
|
|
|
499
|
|
|
500 void complex_fn(_Complex float cf,
|
|
|
501 _Complex double cd,
|
|
|
502 _Complex long double cld)
|
|
|
503 @{
|
|
|
504 printf("cf=%f+%fi\ncd=%f+%fi\ncld=%f+%fi\n",
|
|
|
505 (float)creal (cf), (float)cimag (cf),
|
|
|
506 (float)creal (cd), (float)cimag (cd),
|
|
|
507 (float)creal (cld), (float)cimag (cld));
|
|
|
508 @}
|
|
|
509
|
|
|
510 int main()
|
|
|
511 @{
|
|
|
512 ffi_cif cif;
|
|
|
513 ffi_type *args[3];
|
|
|
514 void *values[3];
|
|
|
515 _Complex float cf;
|
|
|
516 _Complex double cd;
|
|
|
517 _Complex long double cld;
|
|
|
518
|
|
|
519 /* Initialize the argument info vectors */
|
|
|
520 args[0] = &ffi_type_complex_float;
|
|
|
521 args[1] = &ffi_type_complex_double;
|
|
|
522 args[2] = &ffi_type_complex_longdouble;
|
|
|
523 values[0] = &cf;
|
|
|
524 values[1] = &cd;
|
|
|
525 values[2] = &cld;
|
|
|
526
|
|
|
527 /* Initialize the cif */
|
|
|
528 if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 3,
|
|
|
529 &ffi_type_void, args) == FFI_OK)
|
|
|
530 @{
|
|
|
531 cf = 1.0 + 20.0 * I;
|
|
|
532 cd = 300.0 + 4000.0 * I;
|
|
|
533 cld = 50000.0 + 600000.0 * I;
|
|
|
534 /* Call the function */
|
|
|
535 ffi_call(&cif, (void (*)(void))complex_fn, 0, values);
|
|
|
536 @}
|
|
|
537
|
|
|
538 return 0;
|
|
|
539 @}
|
|
|
540 @end example
|
|
|
541
|
|
|
542 This is an example for defining a custom complex type descriptor
|
|
|
543 for compilers that support them:
|
|
|
544
|
|
|
545 @example
|
|
|
546 /*
|
|
|
547 * This macro can be used to define new complex type descriptors
|
|
|
548 * in a platform independent way.
|
|
|
549 *
|
|
|
550 * name: Name of the new descriptor is ffi_type_complex_<name>.
|
|
|
551 * type: The C base type of the complex type.
|
|
|
552 */
|
|
|
553 #define FFI_COMPLEX_TYPEDEF(name, type, ffitype) \
|
|
|
554 static ffi_type *ffi_elements_complex_##name [2] = @{ \
|
|
|
555 (ffi_type *)(&ffitype), NULL \
|
|
|
556 @}; \
|
|
|
557 struct struct_align_complex_##name @{ \
|
|
|
558 char c; \
|
|
|
559 _Complex type x; \
|
|
|
560 @}; \
|
|
|
561 ffi_type ffi_type_complex_##name = @{ \
|
|
|
562 sizeof(_Complex type), \
|
|
|
563 offsetof(struct struct_align_complex_##name, x), \
|
|
|
564 FFI_TYPE_COMPLEX, \
|
|
|
565 (ffi_type **)ffi_elements_complex_##name \
|
|
|
566 @}
|
|
|
567
|
|
|
568 /* Define new complex type descriptors using the macro: */
|
|
|
569 /* ffi_type_complex_sint */
|
|
|
570 FFI_COMPLEX_TYPEDEF(sint, int, ffi_type_sint);
|
|
|
571 /* ffi_type_complex_uchar */
|
|
|
572 FFI_COMPLEX_TYPEDEF(uchar, unsigned char, ffi_type_uint8);
|
|
|
573 @end example
|
|
|
574
|
|
|
575 The new type descriptors can then be used like one of the built-in
|
|
|
576 type descriptors in the previous example.
|
|
|
577
|
|
|
578 @node Multiple ABIs
|
|
|
579 @section Multiple ABIs
|
|
|
580
|
|
|
581 A given platform may provide multiple different ABIs at once. For
|
|
|
582 instance, the x86 platform has both @samp{stdcall} and @samp{fastcall}
|
|
|
583 functions.
|
|
|
584
|
|
|
585 @code{libffi} provides some support for this. However, this is
|
|
|
586 necessarily platform-specific.
|
|
|
587
|
|
|
588 @c FIXME: document the platforms
|
|
|
589
|
|
|
590 @node The Closure API
|
|
|
591 @section The Closure API
|
|
|
592
|
|
|
593 @code{libffi} also provides a way to write a generic function -- a
|
|
|
594 function that can accept and decode any combination of arguments.
|
|
|
595 This can be useful when writing an interpreter, or to provide wrappers
|
|
|
596 for arbitrary functions.
|
|
|
597
|
|
|
598 This facility is called the @dfn{closure API}. Closures are not
|
|
|
599 supported on all platforms; you can check the @code{FFI_CLOSURES}
|
|
|
600 define to determine whether they are supported on the current
|
|
|
601 platform.
|
|
|
602 @cindex closures
|
|
|
603 @cindex closure API
|
|
|
604 @findex FFI_CLOSURES
|
|
|
605
|
|
|
606 Because closures work by assembling a tiny function at runtime, they
|
|
|
607 require special allocation on platforms that have a non-executable
|
|
|
608 heap. Memory management for closures is handled by a pair of
|
|
|
609 functions:
|
|
|
610
|
|
|
611 @findex ffi_closure_alloc
|
|
|
612 @defun void *ffi_closure_alloc (size_t @var{size}, void **@var{code})
|
|
|
613 Allocate a chunk of memory holding @var{size} bytes. This returns a
|
|
|
614 pointer to the writable address, and sets *@var{code} to the
|
|
|
615 corresponding executable address.
|
|
|
616
|
|
|
617 @var{size} should be sufficient to hold a @code{ffi_closure} object.
|
|
|
618 @end defun
|
|
|
619
|
|
|
620 @findex ffi_closure_free
|
|
|
621 @defun void ffi_closure_free (void *@var{writable})
|
|
|
622 Free memory allocated using @code{ffi_closure_alloc}. The argument is
|
|
|
623 the writable address that was returned.
|
|
|
624 @end defun
|
|
|
625
|
|
|
626
|
|
|
627 Once you have allocated the memory for a closure, you must construct a
|
|
|
628 @code{ffi_cif} describing the function call. Finally you can prepare
|
|
|
629 the closure function:
|
|
|
630
|
|
|
631 @findex ffi_prep_closure_loc
|
|
|
632 @defun ffi_status ffi_prep_closure_loc (ffi_closure *@var{closure}, ffi_cif *@var{cif}, void (*@var{fun}) (ffi_cif *@var{cif}, void *@var{ret}, void **@var{args}, void *@var{user_data}), void *@var{user_data}, void *@var{codeloc})
|
|
|
633 Prepare a closure function.
|
|
|
634
|
|
|
635 @var{closure} is the address of a @code{ffi_closure} object; this is
|
|
|
636 the writable address returned by @code{ffi_closure_alloc}.
|
|
|
637
|
|
|
638 @var{cif} is the @code{ffi_cif} describing the function parameters.
|
|
|
639
|
|
|
640 @var{user_data} is an arbitrary datum that is passed, uninterpreted,
|
|
|
641 to your closure function.
|
|
|
642
|
|
|
643 @var{codeloc} is the executable address returned by
|
|
|
644 @code{ffi_closure_alloc}.
|
|
|
645
|
|
|
646 @var{fun} is the function which will be called when the closure is
|
|
|
647 invoked. It is called with the arguments:
|
|
|
648 @table @var
|
|
|
649 @item cif
|
|
|
650 The @code{ffi_cif} passed to @code{ffi_prep_closure_loc}.
|
|
|
651
|
|
|
652 @item ret
|
|
|
653 A pointer to the memory used for the function's return value.
|
|
|
654 @var{fun} must fill this, unless the function is declared as returning
|
|
|
655 @code{void}.
|
|
|
656 @c FIXME: is this NULL for void-returning functions?
|
|
|
657
|
|
|
658 @item args
|
|
|
659 A vector of pointers to memory holding the arguments to the function.
|
|
|
660
|
|
|
661 @item user_data
|
|
|
662 The same @var{user_data} that was passed to
|
|
|
663 @code{ffi_prep_closure_loc}.
|
|
|
664 @end table
|
|
|
665
|
|
|
666 @code{ffi_prep_closure_loc} will return @code{FFI_OK} if everything
|
|
|
667 went ok, and something else on error.
|
|
|
668 @c FIXME: what?
|
|
|
669
|
|
|
670 After calling @code{ffi_prep_closure_loc}, you can cast @var{codeloc}
|
|
|
671 to the appropriate pointer-to-function type.
|
|
|
672 @end defun
|
|
|
673
|
|
|
674 You may see old code referring to @code{ffi_prep_closure}. This
|
|
|
675 function is deprecated, as it cannot handle the need for separate
|
|
|
676 writable and executable addresses.
|
|
|
677
|
|
|
678 @node Closure Example
|
|
|
679 @section Closure Example
|
|
|
680
|
|
|
681 A trivial example that creates a new @code{puts} by binding
|
|
|
682 @code{fputs} with @code{stdout}.
|
|
|
683
|
|
|
684 @example
|
|
|
685 #include <stdio.h>
|
|
|
686 #include <ffi.h>
|
|
|
687
|
|
|
688 /* Acts like puts with the file given at time of enclosure. */
|
|
|
689 void puts_binding(ffi_cif *cif, void *ret, void* args[],
|
|
|
690 void *stream)
|
|
|
691 @{
|
|
|
692 *(ffi_arg *)ret = fputs(*(char **)args[0], (FILE *)stream);
|
|
|
693 @}
|
|
|
694
|
|
|
695 typedef int (*puts_t)(char *);
|
|
|
696
|
|
|
697 int main()
|
|
|
698 @{
|
|
|
699 ffi_cif cif;
|
|
|
700 ffi_type *args[1];
|
|
|
701 ffi_closure *closure;
|
|
|
702
|
|
|
703 void *bound_puts;
|
|
|
704 int rc;
|
|
|
705
|
|
|
706 /* Allocate closure and bound_puts */
|
|
|
707 closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts);
|
|
|
708
|
|
|
709 if (closure)
|
|
|
710 @{
|
|
|
711 /* Initialize the argument info vectors */
|
|
|
712 args[0] = &ffi_type_pointer;
|
|
|
713
|
|
|
714 /* Initialize the cif */
|
|
|
715 if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
|
|
|
716 &ffi_type_sint, args) == FFI_OK)
|
|
|
717 @{
|
|
|
718 /* Initialize the closure, setting stream to stdout */
|
|
|
719 if (ffi_prep_closure_loc(closure, &cif, puts_binding,
|
|
|
720 stdout, bound_puts) == FFI_OK)
|
|
|
721 @{
|
|
|
722 rc = ((puts_t)bound_puts)("Hello World!");
|
|
|
723 /* rc now holds the result of the call to fputs */
|
|
|
724 @}
|
|
|
725 @}
|
|
|
726 @}
|
|
|
727
|
|
|
728 /* Deallocate both closure, and bound_puts */
|
|
|
729 ffi_closure_free(closure);
|
|
|
730
|
|
|
731 return 0;
|
|
|
732 @}
|
|
|
733
|
|
|
734 @end example
|
|
|
735
|
|
|
736
|
|
|
737 @node Missing Features
|
|
|
738 @chapter Missing Features
|
|
|
739
|
|
|
740 @code{libffi} is missing a few features. We welcome patches to add
|
|
|
741 support for these.
|
|
|
742
|
|
|
743 @itemize @bullet
|
|
|
744 @item
|
|
|
745 Variadic closures.
|
|
|
746
|
|
|
747 @item
|
|
|
748 There is no support for bit fields in structures.
|
|
|
749
|
|
|
750 @item
|
|
|
751 The ``raw'' API is undocumented.
|
|
|
752 @c argument promotion?
|
|
|
753 @c unions?
|
|
|
754 @c anything else?
|
|
|
755 @end itemize
|
|
|
756
|
|
|
757 Note that variadic support is very new and tested on a relatively
|
|
|
758 small number of platforms.
|
|
|
759
|
|
|
760 @node Index
|
|
|
761 @unnumbered Index
|
|
|
762
|
|
|
763 @printindex cp
|
|
|
764
|
|
|
765 @bye
|
