Daily bump.
[official-gcc.git] / libffi / doc / libffi.texi
blobb9887a8c65b75a4908cb45ec71e9a419737150a7
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
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
15 @include version.texi
17 @copying
19 This manual is for Libffi, a portable foreign-function interface
20 library.
22 Copyright @copyright{} 2008, 2010, 2011 Red Hat, Inc.
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''.
31 @end quotation
32 @end copying
34 @dircategory Development
35 @direntry
36 * libffi: (libffi).             Portable foreign-function interface library.
37 @end direntry
39 @titlepage
40 @title Libffi
41 @page
42 @vskip 0pt plus 1filll
43 @insertcopying
44 @end titlepage
47 @ifnottex
48 @node Top
49 @top libffi
51 @insertcopying
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
60 @end ifnottex
63 @node Introduction
64 @chapter What is libffi?
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
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.
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.
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
100 @node Using libffi
101 @chapter Using libffi
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
113 @node The Basics
114 @section The Basics
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.
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
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.
132 @var{abi} is the ABI to use; normally @code{FFI_DEFAULT_ABI} is what
133 you want.  @ref{Multiple ABIs} for more information.
135 @var{nargs} is the number of arguments that this function accepts.
137 @var{rtype} is a pointer to an @code{ffi_type} structure that
138 describes the return type of the function.  @xref{Types}.
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.
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
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}.
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:
160 @var{nfixedargs} is the number of fixed arguments, prior to any
161 variadic arguments.  It must be greater than zero.
163 @var{ntotalargs} the total number of arguments, including variadic
164 and fixed arguments.
166 Note that, different cif's must be prepped for calls to the same
167 function when different numbers of arguments are passed.
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}.
173 @end defun
176 To call a function using an initialized @code{ffi_cif}, use the
177 @code{ffi_call} function:
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}.
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.
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
202 @node Simple Example
203 @section Simple Example
205 Here is a trivial example that calls @code{puts} a few times.
207 @example
208 #include <stdio.h>
209 #include <ffi.h>
211 int main()
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;
240 @end example
243 @node Types
244 @section Types
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
254 @node Primitive Types
255 @subsection Primitive Types
257 @code{Libffi} provides a number of built-in type descriptors that can
258 be used to describe argument and return types:
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.
266 @item ffi_type_uint8
267 @tindex ffi_type_uint8
268 An unsigned, 8-bit integer type.
270 @item ffi_type_sint8
271 @tindex ffi_type_sint8
272 A signed, 8-bit integer type.
274 @item ffi_type_uint16
275 @tindex ffi_type_uint16
276 An unsigned, 16-bit integer type.
278 @item ffi_type_sint16
279 @tindex ffi_type_sint16
280 A signed, 16-bit integer type.
282 @item ffi_type_uint32
283 @tindex ffi_type_uint32
284 An unsigned, 32-bit integer type.
286 @item ffi_type_sint32
287 @tindex ffi_type_sint32
288 A signed, 32-bit integer type.
290 @item ffi_type_uint64
291 @tindex ffi_type_uint64
292 An unsigned, 64-bit integer type.
294 @item ffi_type_sint64
295 @tindex ffi_type_sint64
296 A signed, 64-bit integer type.
298 @item ffi_type_float
299 @tindex ffi_type_float
300 The C @code{float} type.
302 @item ffi_type_double
303 @tindex ffi_type_double
304 The C @code{double} type.
306 @item ffi_type_uchar
307 @tindex ffi_type_uchar
308 The C @code{unsigned char} type.
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.)
317 @item ffi_type_ushort
318 @tindex ffi_type_ushort
319 The C @code{unsigned short} type.
321 @item ffi_type_sshort
322 @tindex ffi_type_sshort
323 The C @code{short} type.
325 @item ffi_type_uint
326 @tindex ffi_type_uint
327 The C @code{unsigned int} type.
329 @item ffi_type_sint
330 @tindex ffi_type_sint
331 The C @code{int} type.
333 @item ffi_type_ulong
334 @tindex ffi_type_ulong
335 The C @code{unsigned long} type.
337 @item ffi_type_slong
338 @tindex ffi_type_slong
339 The C @code{long} type.
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.
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.
351 @item ffi_type_complex_float
352 @tindex ffi_type_complex_float
353 The C @code{_Complex float} type.
355 @item ffi_type_complex_double
356 @tindex ffi_type_complex_double
357 The C @code{_Complex double} type.
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
366 Each of these is of type @code{ffi_type}, so you must take the address
367 when passing to @code{ffi_prep_cif}.
370 @node Structures
371 @subsection Structures
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.
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.
385 @item unsigned short alignment
386 This is set by @code{libffi}; you should initialize it to zero.
388 @item unsigned short type
389 For a structure, this should be set to @code{FFI_TYPE_STRUCT}.
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
398 @node Type Example
399 @subsection Type Example
401 The following example initializes a @code{ffi_type} object
402 representing the @code{tm} struct from Linux's @file{time.h}.
404 Here is how the struct is defined:
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__;
421 @end example
423 Here is the corresponding code to describe this struct to
424 @code{libffi}:
426 @example
427     @{
428       ffi_type tm_type;
429       ffi_type *tm_type_elements[12];
430       int i;
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;
439       tm_type_elements[9] = &ffi_type_slong;
440       tm_type_elements[10] = &ffi_type_pointer;
441       tm_type_elements[11] = NULL;
443       /* tm_type can now be used to represent tm argument types and
444          return types for ffi_prep_cif() */
445     @}
446 @end example
448 @node Complex
449 @subsection Complex Types
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}.
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}.
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.
467 @item unsigned short alignment
468 This must be manually set to the alignment of the complex type.
470 @item unsigned short type
471 For a complex type, this must be set to @code{FFI_TYPE_COMPLEX}.
473 @item ffi_type **elements
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
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.
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.
490 @node Complex Type Example
491 @subsection Complex Type Example
493 This example demonstrates how to use complex types:
495 @example
496 #include <stdio.h>
497 #include <ffi.h>
498 #include <complex.h>
500 void complex_fn(_Complex float cf,
501                 _Complex double cd,
502                 _Complex long double cld)
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));
510 int main()
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;
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;
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     @}
538   return 0;
540 @end example
542 This is an example for defining a custom complex type descriptor
543 for compilers that support them:
545 @example
547  * This macro can be used to define new complex type descriptors
548  * in a platform independent way.
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   @}
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
575 The new type descriptors can then be used like one of the built-in
576 type descriptors in the previous example.
578 @node Multiple ABIs
579 @section Multiple ABIs
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.
585 @code{libffi} provides some support for this.  However, this is
586 necessarily platform-specific.
588 @c FIXME: document the platforms
590 @node The Closure API
591 @section The Closure API
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.
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
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:
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.
617 @var{size} should be sufficient to hold a @code{ffi_closure} object.
618 @end defun
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
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:
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.
635 @var{closure} is the address of a @code{ffi_closure} object; this is
636 the writable address returned by @code{ffi_closure_alloc}.
638 @var{cif} is the @code{ffi_cif} describing the function parameters.
640 @var{user_data} is an arbitrary datum that is passed, uninterpreted,
641 to your closure function.
643 @var{codeloc} is the executable address returned by
644 @code{ffi_closure_alloc}.
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}.
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?
658 @item args
659 A vector of pointers to memory holding the arguments to the function.
661 @item user_data
662 The same @var{user_data} that was passed to
663 @code{ffi_prep_closure_loc}.
664 @end table
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?
670 After calling @code{ffi_prep_closure_loc}, you can cast @var{codeloc}
671 to the appropriate pointer-to-function type.
672 @end defun
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.
678 @node Closure Example
679 @section Closure Example
681 A trivial example that creates a new @code{puts} by binding 
682 @code{fputs} with @code{stdout}.
684 @example
685 #include <stdio.h>
686 #include <ffi.h>
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)
692   *(ffi_arg *)ret = fputs(*(char **)args[0], (FILE *)stream);
695 typedef int (*puts_t)(char *);
697 int main()
699   ffi_cif cif;
700   ffi_type *args[1];
701   ffi_closure *closure;
703   void *bound_puts;
704   int rc;
706   /* Allocate closure and bound_puts */
707   closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts);
709   if (closure)
710     @{
711       /* Initialize the argument info vectors */
712       args[0] = &ffi_type_pointer;
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     @}
728   /* Deallocate both closure, and bound_puts */
729   ffi_closure_free(closure);
731   return 0;
734 @end example
737 @node Missing Features
738 @chapter Missing Features
740 @code{libffi} is missing a few features.  We welcome patches to add
741 support for these.
743 @itemize @bullet
744 @item
745 Variadic closures.
747 @item
748 There is no support for bit fields in structures.
750 @item
751 The ``raw'' API is undocumented.
752 @c argument promotion?
753 @c unions?
754 @c anything else?
755 @end itemize
757 Note that variadic support is very new and tested on a relatively
758 small number of platforms.
760 @node Index
761 @unnumbered Index
763 @printindex cp
765 @bye