Correct typos in libffi.texi
[libffi.git] / doc / libffi.texi
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 * Thread Safety::               Thread safety.
111 @end menu
112
113
114 @node The Basics
115 @section The Basics
116
117 @samp{Libffi} assumes that you have a pointer to the function you wish
118 to call and that you know the number and types of arguments to pass
119 it, as well as the return type of the function.
120
121 The first thing you must do is create an @code{ffi_cif} object that
122 matches the signature of the function you wish to call.  This is a
123 separate step because it is common to make multiple calls using a
124 single @code{ffi_cif}.  The @dfn{cif} in @code{ffi_cif} stands for
125 Call InterFace.  To prepare a call interface object, use the function
126 @code{ffi_prep_cif}.
127 @cindex cif
128
129 @findex ffi_prep_cif
130 @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})
131 This initializes @var{cif} according to the given parameters.
132
133 @var{abi} is the ABI to use; normally @code{FFI_DEFAULT_ABI} is what
134 you want.  @ref{Multiple ABIs} for more information.
135
136 @var{nargs} is the number of arguments that this function accepts.
137
138 @var{rtype} is a pointer to an @code{ffi_type} structure that
139 describes the return type of the function.  @xref{Types}.
140
141 @var{argtypes} is a vector of @code{ffi_type} pointers.
142 @var{argtypes} must have @var{nargs} elements.  If @var{nargs} is 0,
143 this argument is ignored.
144
145 @code{ffi_prep_cif} returns a @code{libffi} status code, of type
146 @code{ffi_status}.  This will be either @code{FFI_OK} if everything
147 worked properly; @code{FFI_BAD_TYPEDEF} if one of the @code{ffi_type}
148 objects is incorrect; or @code{FFI_BAD_ABI} if the @var{abi} parameter
149 is invalid.
150 @end defun
151
152 If the function being called is variadic (varargs) then
153 @code{ffi_prep_cif_var} must be used instead of @code{ffi_prep_cif}.
154
155 @findex ffi_prep_cif_var
156 @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})
157 This initializes @var{cif} according to the given parameters for
158 a call to a variadic function.  In general its operation is the
159 same as for @code{ffi_prep_cif} except that:
160
161 @var{nfixedargs} is the number of fixed arguments, prior to any
162 variadic arguments.  It must be greater than zero.
163
164 @var{ntotalargs} the total number of arguments, including variadic
165 and fixed arguments.  @var{argtypes} must have this many elements.
166
167 Note that, different cif's must be prepped for calls to the same
168 function when different numbers of arguments are passed.
169
170 Also note that a call to @code{ffi_prep_cif_var} with
171 @var{nfixedargs}=@var{nototalargs} is NOT equivalent to a call to
172 @code{ffi_prep_cif}.
173
174 @end defun
175
176 Note that the resulting @code{ffi_cif} holds pointers to all the
177 @code{ffi_type} objects that were used during initialization.  You
178 must ensure that these type objects have a lifetime at least as long
179 as that of the @code{ffi_cif}.
180
181 To call a function using an initialized @code{ffi_cif}, use the
182 @code{ffi_call} function:
183
184 @findex ffi_call
185 @defun void ffi_call (ffi_cif *@var{cif}, void *@var{fn}, void *@var{rvalue}, void **@var{avalues})
186 This calls the function @var{fn} according to the description given in
187 @var{cif}.  @var{cif} must have already been prepared using
188 @code{ffi_prep_cif}.
189
190 @var{rvalue} is a pointer to a chunk of memory that will hold the
191 result of the function call.  This must be large enough to hold the
192 result, no smaller than the system register size (generally 32 or 64
193 bits), and must be suitably aligned; it is the caller's responsibility
194 to ensure this.  If @var{cif} declares that the function returns
195 @code{void} (using @code{ffi_type_void}), then @var{rvalue} is
196 ignored.
197
198 In most situations, @samp{libffi} will handle promotion according to
199 the ABI.  However, for historical reasons, there is a special case
200 with return values that must be handled by your code.  In particular,
201 for integral (not @code{struct}) types that are narrower than the
202 system register size, the return value will be widened by
203 @samp{libffi}.  @samp{libffi} provides a type, @code{ffi_arg}, that
204 can be used as the return type.  For example, if the CIF was defined
205 with a return type of @code{char}, @samp{libffi} will try to store a
206 full @code{ffi_arg} into the return value.
207
208 @var{avalues} is a vector of @code{void *} pointers that point to the
209 memory locations holding the argument values for a call.  If @var{cif}
210 declares that the function has no arguments (i.e., @var{nargs} was 0),
211 then @var{avalues} is ignored.  Note that argument values may be
212 modified by the callee (for instance, structs passed by value); the
213 burden of copying pass-by-value arguments is placed on the caller.
214
215 Note that while the return value must be register-sized, arguments
216 should exactly match their declared type.  For example, if an argument
217 is a @code{short}, then the entry in @var{avalues} should point to an
218 object declared as @code{short}; but if the return type is
219 @code{short}, then @var{rvalue} should point to an object declared as
220 a larger type -- usually @code{ffi_arg}.
221 @end defun
222
223
224 @node Simple Example
225 @section Simple Example
226
227 Here is a trivial example that calls @code{puts} a few times.
228
229 @example
230 #include <stdio.h>
231 #include <ffi.h>
232
233 int main()
234 @{
235   ffi_cif cif;
236   ffi_type *args[1];
237   void *values[1];
238   char *s;
239   ffi_arg rc;
240   
241   /* Initialize the argument info vectors */    
242   args[0] = &ffi_type_pointer;
243   values[0] = &s;
244   
245   /* Initialize the cif */
246   if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, 
247                        &ffi_type_sint, args) == FFI_OK)
248     @{
249       s = "Hello World!";
250       ffi_call(&cif, puts, &rc, values);
251       /* rc now holds the result of the call to puts */
252       
253       /* values holds a pointer to the function's arg, so to 
254          call puts() again all we need to do is change the 
255          value of s */
256       s = "This is cool!";
257       ffi_call(&cif, puts, &rc, values);
258     @}
259   
260   return 0;
261 @}
262 @end example
263
264
265 @node Types
266 @section Types
267
268 @menu
269 * Primitive Types::             Built-in types.
270 * Structures::                  Structure types.
271 * Size and Alignment::          Size and alignment of types.
272 * Arrays Unions Enums::         Arrays, unions, and enumerations.
273 * Type Example::                Structure type example.
274 * Complex::                     Complex types.
275 * Complex Type Example::        Complex type example.
276 @end menu
277
278 @node Primitive Types
279 @subsection Primitive Types
280
281 @code{Libffi} provides a number of built-in type descriptors that can
282 be used to describe argument and return types:
283
284 @table @code
285 @item ffi_type_void
286 @tindex ffi_type_void
287 The type @code{void}.  This cannot be used for argument types, only
288 for return values.
289
290 @item ffi_type_uint8
291 @tindex ffi_type_uint8
292 An unsigned, 8-bit integer type.
293
294 @item ffi_type_sint8
295 @tindex ffi_type_sint8
296 A signed, 8-bit integer type.
297
298 @item ffi_type_uint16
299 @tindex ffi_type_uint16
300 An unsigned, 16-bit integer type.
301
302 @item ffi_type_sint16
303 @tindex ffi_type_sint16
304 A signed, 16-bit integer type.
305
306 @item ffi_type_uint32
307 @tindex ffi_type_uint32
308 An unsigned, 32-bit integer type.
309
310 @item ffi_type_sint32
311 @tindex ffi_type_sint32
312 A signed, 32-bit integer type.
313
314 @item ffi_type_uint64
315 @tindex ffi_type_uint64
316 An unsigned, 64-bit integer type.
317
318 @item ffi_type_sint64
319 @tindex ffi_type_sint64
320 A signed, 64-bit integer type.
321
322 @item ffi_type_float
323 @tindex ffi_type_float
324 The C @code{float} type.
325
326 @item ffi_type_double
327 @tindex ffi_type_double
328 The C @code{double} type.
329
330 @item ffi_type_uchar
331 @tindex ffi_type_uchar
332 The C @code{unsigned char} type.
333
334 @item ffi_type_schar
335 @tindex ffi_type_schar
336 The C @code{signed char} type.  (Note that there is not an exact
337 equivalent to the C @code{char} type in @code{libffi}; ordinarily you
338 should either use @code{ffi_type_schar} or @code{ffi_type_uchar}
339 depending on whether @code{char} is signed.)
340
341 @item ffi_type_ushort
342 @tindex ffi_type_ushort
343 The C @code{unsigned short} type.
344
345 @item ffi_type_sshort
346 @tindex ffi_type_sshort
347 The C @code{short} type.
348
349 @item ffi_type_uint
350 @tindex ffi_type_uint
351 The C @code{unsigned int} type.
352
353 @item ffi_type_sint
354 @tindex ffi_type_sint
355 The C @code{int} type.
356
357 @item ffi_type_ulong
358 @tindex ffi_type_ulong
359 The C @code{unsigned long} type.
360
361 @item ffi_type_slong
362 @tindex ffi_type_slong
363 The C @code{long} type.
364
365 @item ffi_type_longdouble
366 @tindex ffi_type_longdouble
367 On platforms that have a C @code{long double} type, this is defined.
368 On other platforms, it is not.
369
370 @item ffi_type_pointer
371 @tindex ffi_type_pointer
372 A generic @code{void *} pointer.  You should use this for all
373 pointers, regardless of their real type.
374
375 @item ffi_type_complex_float
376 @tindex ffi_type_complex_float
377 The C @code{_Complex float} type.
378
379 @item ffi_type_complex_double
380 @tindex ffi_type_complex_double
381 The C @code{_Complex double} type.
382
383 @item ffi_type_complex_longdouble
384 @tindex ffi_type_complex_longdouble
385 The C @code{_Complex long double} type.
386 On platforms that have a C @code{long double} type, this is defined.
387 On other platforms, it is not.
388 @end table
389
390 Each of these is of type @code{ffi_type}, so you must take the address
391 when passing to @code{ffi_prep_cif}.
392
393
394 @node Structures
395 @subsection Structures
396
397 @samp{libffi} is perfectly happy passing structures back and forth.
398 You must first describe the structure to @samp{libffi} by creating a
399 new @code{ffi_type} object for it.
400
401 @tindex ffi_type
402 @deftp {Data type} ffi_type
403 The @code{ffi_type} has the following members:
404 @table @code
405 @item size_t size
406 This is set by @code{libffi}; you should initialize it to zero.
407
408 @item unsigned short alignment
409 This is set by @code{libffi}; you should initialize it to zero.
410
411 @item unsigned short type
412 For a structure, this should be set to @code{FFI_TYPE_STRUCT}.
413
414 @item ffi_type **elements
415 This is a @samp{NULL}-terminated array of pointers to @code{ffi_type}
416 objects.  There is one element per field of the struct.
417
418 Note that @samp{libffi} has no special support for bit-fields.  You
419 must manage these manually.
420 @end table
421 @end deftp
422
423 The @code{size} and @code{alignment} fields will be filled in by
424 @code{ffi_prep_cif} or @code{ffi_prep_cif_var}, as needed.
425
426 @node Size and Alignment
427 @subsection Size and Alignment
428
429 @code{libffi} will set the @code{size} and @code{alignment} fields of
430 an @code{ffi_type} object for you.  It does so using its knowledge of
431 the ABI.
432
433 You might expect that you can simply read these fields for a type that
434 has been laid out by @code{libffi}.  However, there are some caveats.
435
436 @itemize @bullet
437 @item
438 The size or alignment of some of the built-in types may vary depending
439 on the chosen ABI.
440
441 @item
442 The size and alignment of a new structure type will not be set by
443 @code{libffi} until it has been passed to @code{ffi_prep_cif} or
444 @code{ffi_get_struct_offsets}.
445
446 @item
447 A structure type cannot be shared across ABIs.  Instead each ABI needs
448 its own copy of the structure type.
449 @end itemize
450
451 So, before examining these fields, it is safest to pass the
452 @code{ffi_type} object to @code{ffi_prep_cif} or
453 @code{ffi_get_struct_offsets} first.  This function will do all the
454 needed setup.
455
456 @example
457 ffi_type *desired_type;
458 ffi_abi desired_abi;
459 @dots{}
460 ffi_cif cif;
461 if (ffi_prep_cif (&cif, desired_abi, 0, desired_type, NULL) == FFI_OK)
462   @{
463     size_t size = desired_type->size;
464     unsigned short alignment = desired_type->alignment;
465   @}
466 @end example
467
468 @code{libffi} also provides a way to get the offsets of the members of
469 a structure.
470
471 @findex ffi_get_struct_offsets
472 @defun ffi_status ffi_get_struct_offsets (ffi_abi abi, ffi_type *struct_type, size_t *offsets)
473 Compute the offset of each element of the given structure type.
474 @var{abi} is the ABI to use; this is needed because in some cases the
475 layout depends on the ABI.
476
477 @var{offsets} is an out parameter.  The caller is responsible for
478 providing enough space for all the results to be written -- one
479 element per element type in @var{struct_type}.  If @var{offsets} is
480 @code{NULL}, then the type will be laid out but not otherwise
481 modified.  This can be useful for accessing the type's size or layout,
482 as mentioned above.
483
484 This function returns @code{FFI_OK} on success; @code{FFI_BAD_ABI} if
485 @var{abi} is invalid; or @code{FFI_BAD_TYPEDEF} if @var{struct_type}
486 is invalid in some way.  Note that only @code{FFI_STRUCT} types are
487 valid here.
488 @end defun
489
490 @node Arrays Unions Enums
491 @subsection Arrays, Unions, and Enumerations
492
493 @subsubsection Arrays
494
495 @samp{libffi} does not have direct support for arrays or unions.
496 However, they can be emulated using structures.
497
498 To emulate an array, simply create an @code{ffi_type} using
499 @code{FFI_TYPE_STRUCT} with as many members as there are elements in
500 the array.
501
502 @example
503 ffi_type array_type;
504 ffi_type **elements
505 int i;
506
507 elements = malloc ((n + 1) * sizeof (ffi_type *));
508 for (i = 0; i < n; ++i)
509   elements[i] = array_element_type;
510 elements[n] = NULL;
511
512 array_type.size = array_type.alignment = 0;
513 array_type.type = FFI_TYPE_STRUCT;
514 array_type.elements = elements;
515 @end example
516
517 Note that arrays cannot be passed or returned by value in C --
518 structure types created like this should only be used to refer to
519 members of real @code{FFI_TYPE_STRUCT} objects.
520
521 However, a phony array type like this will not cause any errors from
522 @samp{libffi} if you use it as an argument or return type.  This may
523 be confusing.
524
525 @subsubsection Unions
526
527 A union can also be emulated using @code{FFI_TYPE_STRUCT}.  In this
528 case, however, you must make sure that the size and alignment match
529 the real requirements of the union.
530
531 One simple way to do this is to ensue that each element type is laid
532 out.  Then, give the new structure type a single element; the size of
533 the largest element; and the largest alignment seen as well.
534
535 This example uses the @code{ffi_prep_cif} trick to ensure that each
536 element type is laid out.
537
538 @example
539 ffi_abi desired_abi;
540 ffi_type union_type;
541 ffi_type **union_elements;
542
543 int i;
544 ffi_type element_types[2];
545
546 element_types[1] = NULL;
547
548 union_type.size = union_type.alignment = 0;
549 union_type.type = FFI_TYPE_STRUCT;
550 union_type.elements = element_types;
551
552 for (i = 0; union_elements[i]; ++i)
553   @{
554     ffi_cif cif;
555     if (ffi_prep_cif (&cif, desired_abi, 0, union_elements[i], NULL) == FFI_OK)
556       @{
557         if (union_elements[i]->size > union_type.size)
558           @{
559             union_type.size = union_elements[i];
560             size = union_elements[i]->size;
561           @}
562         if (union_elements[i]->alignment > union_type.alignment)
563           union_type.alignment = union_elements[i]->alignment;
564       @}
565   @}
566 @end example
567
568 @subsubsection Enumerations
569
570 @code{libffi} does not have any special support for C @code{enum}s.
571 Although any given @code{enum} is implemented using a specific
572 underlying integral type, exactly which type will be used cannot be
573 determined by @code{libffi} -- it may depend on the values in the
574 enumeration or on compiler flags such as @option{-fshort-enums}.
575 @xref{Structures unions enumerations and bit-fields implementation, , , gcc},
576 for more information about how GCC handles enumerations.
577
578 @node Type Example
579 @subsection Type Example
580
581 The following example initializes a @code{ffi_type} object
582 representing the @code{tm} struct from Linux's @file{time.h}.
583
584 Here is how the struct is defined:
585
586 @example
587 struct tm @{
588     int tm_sec;
589     int tm_min;
590     int tm_hour;
591     int tm_mday;
592     int tm_mon;
593     int tm_year;
594     int tm_wday;
595     int tm_yday;
596     int tm_isdst;
597     /* Those are for future use. */
598     long int __tm_gmtoff__;
599     __const char *__tm_zone__;
600 @};
601 @end example
602
603 Here is the corresponding code to describe this struct to
604 @code{libffi}:
605
606 @example
607     @{
608       ffi_type tm_type;
609       ffi_type *tm_type_elements[12];
610       int i;
611
612       tm_type.size = tm_type.alignment = 0;
613       tm_type.type = FFI_TYPE_STRUCT;
614       tm_type.elements = &tm_type_elements;
615     
616       for (i = 0; i < 9; i++)
617           tm_type_elements[i] = &ffi_type_sint;
618
619       tm_type_elements[9] = &ffi_type_slong;
620       tm_type_elements[10] = &ffi_type_pointer;
621       tm_type_elements[11] = NULL;
622
623       /* tm_type can now be used to represent tm argument types and
624          return types for ffi_prep_cif() */
625     @}
626 @end example
627
628 @node Complex
629 @subsection Complex Types
630
631 @samp{libffi} supports the complex types defined by the C99
632 standard (@code{_Complex float}, @code{_Complex double} and
633 @code{_Complex long double} with the built-in type descriptors
634 @code{ffi_type_complex_float}, @code{ffi_type_complex_double} and
635 @code{ffi_type_complex_longdouble}.
636
637 Custom complex types like @code{_Complex int} can also be used.
638 An @code{ffi_type} object has to be defined to describe the
639 complex type to @samp{libffi}.
640
641 @tindex ffi_type
642 @deftp {Data type} ffi_type
643 @table @code
644 @item size_t size
645 This must be manually set to the size of the complex type.
646
647 @item unsigned short alignment
648 This must be manually set to the alignment of the complex type.
649
650 @item unsigned short type
651 For a complex type, this must be set to @code{FFI_TYPE_COMPLEX}.
652
653 @item ffi_type **elements
654
655 This is a @samp{NULL}-terminated array of pointers to
656 @code{ffi_type} objects.  The first element is set to the
657 @code{ffi_type} of the complex's base type.  The second element
658 must be set to @code{NULL}.
659 @end table
660 @end deftp
661
662 The section @ref{Complex Type Example} shows a way to determine
663 the @code{size} and @code{alignment} members in a platform
664 independent way.
665
666 For platforms that have no complex support in @code{libffi} yet,
667 the functions @code{ffi_prep_cif} and @code{ffi_prep_args} abort
668 the program if they encounter a complex type.
669
670 @node Complex Type Example
671 @subsection Complex Type Example
672
673 This example demonstrates how to use complex types:
674
675 @example
676 #include <stdio.h>
677 #include <ffi.h>
678 #include <complex.h>
679
680 void complex_fn(_Complex float cf,
681                 _Complex double cd,
682                 _Complex long double cld)
683 @{
684   printf("cf=%f+%fi\ncd=%f+%fi\ncld=%f+%fi\n",
685          (float)creal (cf), (float)cimag (cf),
686          (float)creal (cd), (float)cimag (cd),
687          (float)creal (cld), (float)cimag (cld));
688 @}
689
690 int main()
691 @{
692   ffi_cif cif;
693   ffi_type *args[3];
694   void *values[3];
695   _Complex float cf;
696   _Complex double cd;
697   _Complex long double cld;
698
699   /* Initialize the argument info vectors */
700   args[0] = &ffi_type_complex_float;
701   args[1] = &ffi_type_complex_double;
702   args[2] = &ffi_type_complex_longdouble;
703   values[0] = &cf;
704   values[1] = &cd;
705   values[2] = &cld;
706
707   /* Initialize the cif */
708   if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 3,
709                    &ffi_type_void, args) == FFI_OK)
710     @{
711       cf = 1.0 + 20.0 * I;
712       cd = 300.0 + 4000.0 * I;
713       cld = 50000.0 + 600000.0 * I;
714       /* Call the function */
715       ffi_call(&cif, (void (*)(void))complex_fn, 0, values);
716     @}
717
718   return 0;
719 @}
720 @end example
721
722 This is an example for defining a custom complex type descriptor
723 for compilers that support them:
724
725 @example
726 /*
727  * This macro can be used to define new complex type descriptors
728  * in a platform independent way.
729  *
730  * name: Name of the new descriptor is ffi_type_complex_<name>.
731  * type: The C base type of the complex type.
732  */
733 #define FFI_COMPLEX_TYPEDEF(name, type, ffitype)             \
734   static ffi_type *ffi_elements_complex_##name [2] = @{      \
735     (ffi_type *)(&ffitype), NULL                             \
736   @};                                                        \
737   struct struct_align_complex_##name @{                      \
738     char c;                                                  \
739     _Complex type x;                                         \
740   @};                                                        \
741   ffi_type ffi_type_complex_##name = @{                      \
742     sizeof(_Complex type),                                   \
743     offsetof(struct struct_align_complex_##name, x),         \
744     FFI_TYPE_COMPLEX,                                        \
745     (ffi_type **)ffi_elements_complex_##name                 \
746   @}
747
748 /* Define new complex type descriptors using the macro: */
749 /* ffi_type_complex_sint */
750 FFI_COMPLEX_TYPEDEF(sint, int, ffi_type_sint);
751 /* ffi_type_complex_uchar */
752 FFI_COMPLEX_TYPEDEF(uchar, unsigned char, ffi_type_uint8);
753 @end example
754
755 The new type descriptors can then be used like one of the built-in
756 type descriptors in the previous example.
757
758 @node Multiple ABIs
759 @section Multiple ABIs
760
761 A given platform may provide multiple different ABIs at once.  For
762 instance, the x86 platform has both @samp{stdcall} and @samp{fastcall}
763 functions.
764
765 @code{libffi} provides some support for this.  However, this is
766 necessarily platform-specific.
767
768 @c FIXME: document the platforms
769
770 @node The Closure API
771 @section The Closure API
772
773 @code{libffi} also provides a way to write a generic function -- a
774 function that can accept and decode any combination of arguments.
775 This can be useful when writing an interpreter, or to provide wrappers
776 for arbitrary functions.
777
778 This facility is called the @dfn{closure API}.  Closures are not
779 supported on all platforms; you can check the @code{FFI_CLOSURES}
780 define to determine whether they are supported on the current
781 platform.
782 @cindex closures
783 @cindex closure API
784 @findex FFI_CLOSURES
785
786 Because closures work by assembling a tiny function at runtime, they
787 require special allocation on platforms that have a non-executable
788 heap.  Memory management for closures is handled by a pair of
789 functions:
790
791 @findex ffi_closure_alloc
792 @defun void *ffi_closure_alloc (size_t @var{size}, void **@var{code})
793 Allocate a chunk of memory holding @var{size} bytes.  This returns a
794 pointer to the writable address, and sets *@var{code} to the
795 corresponding executable address.
796
797 @var{size} should be sufficient to hold a @code{ffi_closure} object.
798 @end defun
799
800 @findex ffi_closure_free
801 @defun void ffi_closure_free (void *@var{writable})
802 Free memory allocated using @code{ffi_closure_alloc}.  The argument is
803 the writable address that was returned.
804 @end defun
805
806
807 Once you have allocated the memory for a closure, you must construct a
808 @code{ffi_cif} describing the function call.  Finally you can prepare
809 the closure function:
810
811 @findex ffi_prep_closure_loc
812 @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})
813 Prepare a closure function.  The arguments to
814 @code{ffi_prep_closure_loc} are:
815
816 @table @var
817 @item closure
818 The address of a @code{ffi_closure} object; this is the writable
819 address returned by @code{ffi_closure_alloc}.
820
821 @item cif
822 The @code{ffi_cif} describing the function parameters.  Note that this
823 object, and the types to which it refers, must be kept alive until the
824 closure itself is freed.
825
826 @item user_data
827 An arbitrary datum that is passed, uninterpreted, to your closure
828 function.
829
830 @item codeloc
831 The executable address returned by @code{ffi_closure_alloc}.
832
833 @item fun
834 The function which will be called when the closure is invoked.  It is
835 called with the arguments:
836
837 @table @var
838 @item cif
839 The @code{ffi_cif} passed to @code{ffi_prep_closure_loc}.
840
841 @item ret
842 A pointer to the memory used for the function's return value.
843
844 If the function is declared as returning @code{void}, then this value
845 is garbage and should not be used.
846
847 Otherwise, @var{fun} must fill the object to which this points,
848 following the same special promotion behavior as @code{ffi_call}.
849 That is, in most cases, @var{ret} points to an object of exactly the
850 size of the type specified when @var{cif} was constructed.  However,
851 integral types narrower than the system register size are widened.  In
852 these cases your program may assume that @var{ret} points to an
853 @code{ffi_arg} object.
854
855 @item args
856 A vector of pointers to memory holding the arguments to the function.
857
858 @item user_data
859 The same @var{user_data} that was passed to
860 @code{ffi_prep_closure_loc}.
861 @end table
862 @end table
863
864 @code{ffi_prep_closure_loc} will return @code{FFI_OK} if everything
865 went ok, and one of the other @code{ffi_status} values on error.
866
867 After calling @code{ffi_prep_closure_loc}, you can cast @var{codeloc}
868 to the appropriate pointer-to-function type.
869 @end defun
870
871 You may see old code referring to @code{ffi_prep_closure}.  This
872 function is deprecated, as it cannot handle the need for separate
873 writable and executable addresses.
874
875 @node Closure Example
876 @section Closure Example
877
878 A trivial example that creates a new @code{puts} by binding 
879 @code{fputs} with @code{stdout}.
880
881 @example
882 #include <stdio.h>
883 #include <ffi.h>
884
885 /* Acts like puts with the file given at time of enclosure. */
886 void puts_binding(ffi_cif *cif, void *ret, void* args[],
887                   void *stream)
888 @{
889   *(ffi_arg *)ret = fputs(*(char **)args[0], (FILE *)stream);
890 @}
891
892 typedef int (*puts_t)(char *);
893
894 int main()
895 @{
896   ffi_cif cif;
897   ffi_type *args[1];
898   ffi_closure *closure;
899
900   void *bound_puts;
901   int rc;
902
903   /* Allocate closure and bound_puts */
904   closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts);
905
906   if (closure)
907     @{
908       /* Initialize the argument info vectors */
909       args[0] = &ffi_type_pointer;
910
911       /* Initialize the cif */
912       if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
913                        &ffi_type_sint, args) == FFI_OK)
914         @{
915           /* Initialize the closure, setting stream to stdout */
916           if (ffi_prep_closure_loc(closure, &cif, puts_binding,
917                                    stdout, bound_puts) == FFI_OK)
918             @{
919               rc = ((puts_t)bound_puts)("Hello World!");
920               /* rc now holds the result of the call to fputs */
921             @}
922         @}
923     @}
924
925   /* Deallocate both closure, and bound_puts */
926   ffi_closure_free(closure);
927
928   return 0;
929 @}
930
931 @end example
932
933 @node Thread Safety
934 @section Thread Safety
935
936 @code{libffi} is not completely thread-safe.  However, many parts are,
937 and if you follow some simple rules, you can use it safely in a
938 multi-threaded program.
939
940 @itemize @bullet
941 @item
942 @code{ffi_prep_cif} may modify the @code{ffi_type} objects passed to
943 it.  It is best to ensure that only a single thread prepares a given
944 @code{ffi_cif} at a time.
945
946 @item
947 On some platforms, @code{ffi_prep_cif} may modify the size and
948 alignment of some types, depending on the chosen ABI.  On these
949 platforms, if you switch between ABIs, you must ensure that there is
950 only one call to @code{ffi_prep_cif} at a time.
951
952 Currently the only affected platform is PowerPC and the only affected
953 type is @code{long double}.
954 @end itemize
955
956 @node Missing Features
957 @chapter Missing Features
958
959 @code{libffi} is missing a few features.  We welcome patches to add
960 support for these.
961
962 @itemize @bullet
963 @item
964 Variadic closures.
965
966 @item
967 There is no support for bit fields in structures.
968
969 @item
970 The ``raw'' API is undocumented.
971 @c anything else?
972
973 @item
974 The Go API is undocumented.
975 @end itemize
976
977 Note that variadic support is very new and tested on a relatively
978 small number of platforms.
979
980 @node Index
981 @unnumbered Index
982
983 @printindex cp
984
985 @bye