fix formatting of ffi_prep_closure_loc arguments
[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 it's 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 is @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 and Unions::           Arrays and unions.
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}.
444
445 @item
446 A structure type cannot be shared across ABIs.  Instead each ABI needs
447 its own copy of the structure type.
448 @end itemize
449
450 So, before examining these fields, it is safest to pass the
451 @code{ffi_type} object to @code{ffi_prep_cif} first.  This function
452 will do all the needed setup.
453
454 @example
455 ffi_type *desired_type;
456 ffi_abi desired_abi;
457 @dots{}
458 ffi_cif cif;
459 if (ffi_prep_cif (&cif, desired_abi, 0, desired_type, NULL) == FFI_OK)
460   @{
461     size_t size = desired_type->size;
462     unsigned short alignment = desired_type->alignment;
463   @}
464 @end example
465
466 @node Arrays and Unions
467 @subsection Arrays and Unions
468
469 @subsubsection Arrays
470
471 @samp{libffi} does not have direct support for arrays or unions.
472 However, they can be emulated using structures.
473
474 To emulate an array, simply create an @code{ffi_type} using
475 @code{FFI_TYPE_STRUCT} with as many members as there are elements in
476 the array.
477
478 @example
479 ffi_type array_type;
480 ffi_type **elements
481 int i;
482
483 elements = malloc ((n + 1) * sizeof (ffi_type *));
484 for (i = 0; i < n; ++i)
485   elements[i] = array_element_type;
486 elements[n] = NULL;
487
488 array_type.size = array_type.alignment = 0;
489 array_type.type = FFI_TYPE_STRUCT;
490 array_type.elements = elements;
491 @end example
492
493 Note that arrays cannot be passed or returned by value in C --
494 structure types created like this should only be used to refer to
495 members of real @code{FFI_TYPE_STRUCT} objects.
496
497 However, a phony array type like this will not cause any errors from
498 @samp{libffi} if you use it as an argument or return type.  This may
499 be confusing.
500
501 @subsubsection Unions
502
503 A union can also be emulated using @code{FFI_TYPE_STRUCT}.  In this
504 case, however, you must make sure that the size and alignment match
505 the real requirements of the union.
506
507 One simple way to do this is to ensue that each element type is laid
508 out.  Then, give the new structure type a single element; the size of
509 the largest element; and the largest alignment seen as well.
510
511 This example uses the @code{ffi_prep_cif} trick to ensure that each
512 element type is laid out.
513
514 @example
515 ffi_abi desired_abi;
516 ffi_type union_type;
517 ffi_type **union_elements;
518
519 int i;
520 ffi_type element_types[2];
521
522 element_types[1] = NULL;
523
524 union_type.size = union_type.alignment = 0;
525 union_type.type = FFI_TYPE_STRUCT;
526 union_type.elements = element_types;
527
528 for (i = 0; union_elements[i]; ++i)
529   @{
530     ffi_cif cif;
531     if (ffi_prep_cif (&cif, desired_abi, 0, union_elements[i], NULL) == FFI_OK)
532       @{
533         if (union_elements[i]->size > union_type.size)
534           @{
535             union_type.size = union_elements[i];
536             size = union_elements[i]->size;
537           @}
538         if (union_elements[i]->alignment > union_type.alignment)
539           union_type.alignment = union_elements[i]->alignment;
540       @}
541   @}
542 @end example
543
544 @node Type Example
545 @subsection Type Example
546
547 The following example initializes a @code{ffi_type} object
548 representing the @code{tm} struct from Linux's @file{time.h}.
549
550 Here is how the struct is defined:
551
552 @example
553 struct tm @{
554     int tm_sec;
555     int tm_min;
556     int tm_hour;
557     int tm_mday;
558     int tm_mon;
559     int tm_year;
560     int tm_wday;
561     int tm_yday;
562     int tm_isdst;
563     /* Those are for future use. */
564     long int __tm_gmtoff__;
565     __const char *__tm_zone__;
566 @};
567 @end example
568
569 Here is the corresponding code to describe this struct to
570 @code{libffi}:
571
572 @example
573     @{
574       ffi_type tm_type;
575       ffi_type *tm_type_elements[12];
576       int i;
577
578       tm_type.size = tm_type.alignment = 0;
579       tm_type.type = FFI_TYPE_STRUCT;
580       tm_type.elements = &tm_type_elements;
581     
582       for (i = 0; i < 9; i++)
583           tm_type_elements[i] = &ffi_type_sint;
584
585       tm_type_elements[9] = &ffi_type_slong;
586       tm_type_elements[10] = &ffi_type_pointer;
587       tm_type_elements[11] = NULL;
588
589       /* tm_type can now be used to represent tm argument types and
590          return types for ffi_prep_cif() */
591     @}
592 @end example
593
594 @node Complex
595 @subsection Complex Types
596
597 @samp{libffi} supports the complex types defined by the C99
598 standard (@code{_Complex float}, @code{_Complex double} and
599 @code{_Complex long double} with the built-in type descriptors
600 @code{ffi_type_complex_float}, @code{ffi_type_complex_double} and
601 @code{ffi_type_complex_longdouble}.
602
603 Custom complex types like @code{_Complex int} can also be used.
604 An @code{ffi_type} object has to be defined to describe the
605 complex type to @samp{libffi}.
606
607 @tindex ffi_type
608 @deftp {Data type} ffi_type
609 @table @code
610 @item size_t size
611 This must be manually set to the size of the complex type.
612
613 @item unsigned short alignment
614 This must be manually set to the alignment of the complex type.
615
616 @item unsigned short type
617 For a complex type, this must be set to @code{FFI_TYPE_COMPLEX}.
618
619 @item ffi_type **elements
620
621 This is a @samp{NULL}-terminated array of pointers to
622 @code{ffi_type} objects.  The first element is set to the
623 @code{ffi_type} of the complex's base type.  The second element
624 must be set to @code{NULL}.
625 @end table
626 @end deftp
627
628 The section @ref{Complex Type Example} shows a way to determine
629 the @code{size} and @code{alignment} members in a platform
630 independent way.
631
632 For platforms that have no complex support in @code{libffi} yet,
633 the functions @code{ffi_prep_cif} and @code{ffi_prep_args} abort
634 the program if they encounter a complex type.
635
636 @node Complex Type Example
637 @subsection Complex Type Example
638
639 This example demonstrates how to use complex types:
640
641 @example
642 #include <stdio.h>
643 #include <ffi.h>
644 #include <complex.h>
645
646 void complex_fn(_Complex float cf,
647                 _Complex double cd,
648                 _Complex long double cld)
649 @{
650   printf("cf=%f+%fi\ncd=%f+%fi\ncld=%f+%fi\n",
651          (float)creal (cf), (float)cimag (cf),
652          (float)creal (cd), (float)cimag (cd),
653          (float)creal (cld), (float)cimag (cld));
654 @}
655
656 int main()
657 @{
658   ffi_cif cif;
659   ffi_type *args[3];
660   void *values[3];
661   _Complex float cf;
662   _Complex double cd;
663   _Complex long double cld;
664
665   /* Initialize the argument info vectors */
666   args[0] = &ffi_type_complex_float;
667   args[1] = &ffi_type_complex_double;
668   args[2] = &ffi_type_complex_longdouble;
669   values[0] = &cf;
670   values[1] = &cd;
671   values[2] = &cld;
672
673   /* Initialize the cif */
674   if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 3,
675                    &ffi_type_void, args) == FFI_OK)
676     @{
677       cf = 1.0 + 20.0 * I;
678       cd = 300.0 + 4000.0 * I;
679       cld = 50000.0 + 600000.0 * I;
680       /* Call the function */
681       ffi_call(&cif, (void (*)(void))complex_fn, 0, values);
682     @}
683
684   return 0;
685 @}
686 @end example
687
688 This is an example for defining a custom complex type descriptor
689 for compilers that support them:
690
691 @example
692 /*
693  * This macro can be used to define new complex type descriptors
694  * in a platform independent way.
695  *
696  * name: Name of the new descriptor is ffi_type_complex_<name>.
697  * type: The C base type of the complex type.
698  */
699 #define FFI_COMPLEX_TYPEDEF(name, type, ffitype)             \
700   static ffi_type *ffi_elements_complex_##name [2] = @{      \
701     (ffi_type *)(&ffitype), NULL                             \
702   @};                                                        \
703   struct struct_align_complex_##name @{                      \
704     char c;                                                  \
705     _Complex type x;                                         \
706   @};                                                        \
707   ffi_type ffi_type_complex_##name = @{                      \
708     sizeof(_Complex type),                                   \
709     offsetof(struct struct_align_complex_##name, x),         \
710     FFI_TYPE_COMPLEX,                                        \
711     (ffi_type **)ffi_elements_complex_##name                 \
712   @}
713
714 /* Define new complex type descriptors using the macro: */
715 /* ffi_type_complex_sint */
716 FFI_COMPLEX_TYPEDEF(sint, int, ffi_type_sint);
717 /* ffi_type_complex_uchar */
718 FFI_COMPLEX_TYPEDEF(uchar, unsigned char, ffi_type_uint8);
719 @end example
720
721 The new type descriptors can then be used like one of the built-in
722 type descriptors in the previous example.
723
724 @node Multiple ABIs
725 @section Multiple ABIs
726
727 A given platform may provide multiple different ABIs at once.  For
728 instance, the x86 platform has both @samp{stdcall} and @samp{fastcall}
729 functions.
730
731 @code{libffi} provides some support for this.  However, this is
732 necessarily platform-specific.
733
734 @c FIXME: document the platforms
735
736 @node The Closure API
737 @section The Closure API
738
739 @code{libffi} also provides a way to write a generic function -- a
740 function that can accept and decode any combination of arguments.
741 This can be useful when writing an interpreter, or to provide wrappers
742 for arbitrary functions.
743
744 This facility is called the @dfn{closure API}.  Closures are not
745 supported on all platforms; you can check the @code{FFI_CLOSURES}
746 define to determine whether they are supported on the current
747 platform.
748 @cindex closures
749 @cindex closure API
750 @findex FFI_CLOSURES
751
752 Because closures work by assembling a tiny function at runtime, they
753 require special allocation on platforms that have a non-executable
754 heap.  Memory management for closures is handled by a pair of
755 functions:
756
757 @findex ffi_closure_alloc
758 @defun void *ffi_closure_alloc (size_t @var{size}, void **@var{code})
759 Allocate a chunk of memory holding @var{size} bytes.  This returns a
760 pointer to the writable address, and sets *@var{code} to the
761 corresponding executable address.
762
763 @var{size} should be sufficient to hold a @code{ffi_closure} object.
764 @end defun
765
766 @findex ffi_closure_free
767 @defun void ffi_closure_free (void *@var{writable})
768 Free memory allocated using @code{ffi_closure_alloc}.  The argument is
769 the writable address that was returned.
770 @end defun
771
772
773 Once you have allocated the memory for a closure, you must construct a
774 @code{ffi_cif} describing the function call.  Finally you can prepare
775 the closure function:
776
777 @findex ffi_prep_closure_loc
778 @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})
779 Prepare a closure function.  The arguments to
780 @code{ffi_prep_closure_loc} are:
781
782 @table @var
783 @item closure
784 The address of a @code{ffi_closure} object; this is the writable
785 address returned by @code{ffi_closure_alloc}.
786
787 @item cif
788 The @code{ffi_cif} describing the function parameters.  Note that this
789 object, and the types to which it refers, must be kept alive until the
790 closure itself is freed.
791
792 @item user_data
793 An arbitrary datum that is passed, uninterpreted, to your closure
794 function.
795
796 @item codeloc
797 The executable address returned by @code{ffi_closure_alloc}.
798
799 @item fun
800 The function which will be called when the closure is invoked.  It is
801 called with the arguments:
802
803 @table @var
804 @item cif
805 The @code{ffi_cif} passed to @code{ffi_prep_closure_loc}.
806
807 @item ret
808 A pointer to the memory used for the function's return value.
809 @var{fun} must fill this, unless the function is declared as returning
810 @code{void}.  Note that this points to memory that is exactly the size
811 of the type given as the return type when initializing the CIF.  In
812 particular, closures do not have the special promotion behavior of
813 @code{ffi_call}.
814 @c FIXME: is this NULL for void-returning functions?
815 @c (experimentally it is not, but it seems like a good idea)
816
817 @item args
818 A vector of pointers to memory holding the arguments to the function.
819
820 @item user_data
821 The same @var{user_data} that was passed to
822 @code{ffi_prep_closure_loc}.
823 @end table
824 @end table
825
826 @code{ffi_prep_closure_loc} will return @code{FFI_OK} if everything
827 went ok, and one of the other @code{ffi_status} values on error.
828
829 After calling @code{ffi_prep_closure_loc}, you can cast @var{codeloc}
830 to the appropriate pointer-to-function type.
831 @end defun
832
833 You may see old code referring to @code{ffi_prep_closure}.  This
834 function is deprecated, as it cannot handle the need for separate
835 writable and executable addresses.
836
837 @node Closure Example
838 @section Closure Example
839
840 A trivial example that creates a new @code{puts} by binding 
841 @code{fputs} with @code{stdout}.
842
843 @example
844 #include <stdio.h>
845 #include <ffi.h>
846
847 /* Acts like puts with the file given at time of enclosure. */
848 void puts_binding(ffi_cif *cif, void *ret, void* args[],
849                   void *stream)
850 @{
851   *(ffi_arg *)ret = fputs(*(char **)args[0], (FILE *)stream);
852 @}
853
854 typedef int (*puts_t)(char *);
855
856 int main()
857 @{
858   ffi_cif cif;
859   ffi_type *args[1];
860   ffi_closure *closure;
861
862   void *bound_puts;
863   int rc;
864
865   /* Allocate closure and bound_puts */
866   closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts);
867
868   if (closure)
869     @{
870       /* Initialize the argument info vectors */
871       args[0] = &ffi_type_pointer;
872
873       /* Initialize the cif */
874       if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
875                        &ffi_type_sint, args) == FFI_OK)
876         @{
877           /* Initialize the closure, setting stream to stdout */
878           if (ffi_prep_closure_loc(closure, &cif, puts_binding,
879                                    stdout, bound_puts) == FFI_OK)
880             @{
881               rc = ((puts_t)bound_puts)("Hello World!");
882               /* rc now holds the result of the call to fputs */
883             @}
884         @}
885     @}
886
887   /* Deallocate both closure, and bound_puts */
888   ffi_closure_free(closure);
889
890   return 0;
891 @}
892
893 @end example
894
895 @node Thread Safety
896 @section Thread Safety
897
898 @code{libffi} is not completely thread-safe.  However, many parts are,
899 and if you follow some simple rules, you can use it safely in a
900 multi-threaded program.
901
902 @itemize @bullet
903 @item
904 @code{ffi_prep_cif} may modify the @code{ffi_type} objects passed to
905 it.  It is best to ensure that only a single thread prepares a given
906 @code{ffi_cif} at a time.
907
908 @item
909 On some platforms, @code{ffi_prep_cif} may modify the size and
910 alignment of some types, depending on the chosen ABI.  On these
911 platforms, if you switch between ABIs, you must ensure that there is
912 only one call to @code{ffi_prep_cif} at a time.
913
914 Currently the only affected platform is PowerPC and the only affected
915 type is @code{long double}.
916 @end itemize
917
918 @node Missing Features
919 @chapter Missing Features
920
921 @code{libffi} is missing a few features.  We welcome patches to add
922 support for these.
923
924 @itemize @bullet
925 @item
926 Variadic closures.
927
928 @item
929 There is no support for bit fields in structures.
930
931 @item
932 The ``raw'' API is undocumented.
933 @c anything else?
934
935 @item
936 The Go API is undocumented.
937 @end itemize
938
939 Note that variadic support is very new and tested on a relatively
940 small number of platforms.
941
942 @node Index
943 @unnumbered Index
944
945 @printindex cp
946
947 @bye