Update libtool version, README, tests dists
[libffi.git] / doc / libffi.info
1 This is ../libffi/doc/libffi.info, produced by makeinfo version 4.13
2 from ../libffi/doc/libffi.texi.
3
4 This manual is for Libffi, a portable foreign-function interface
5 library.
6
7    Copyright (C) 2008, 2010, 2011 Red Hat, Inc.
8
9      Permission is granted to copy, distribute and/or modify this
10      document under the terms of the GNU General Public License as
11      published by the Free Software Foundation; either version 2, or
12      (at your option) any later version.  A copy of the license is
13      included in the section entitled "GNU General Public License".
14
15
16 INFO-DIR-SECTION Development
17 START-INFO-DIR-ENTRY
18 * libffi: (libffi).             Portable foreign-function interface library.
19 END-INFO-DIR-ENTRY
20
21 \1f
22 File: libffi.info,  Node: Top,  Next: Introduction,  Up: (dir)
23
24 libffi
25 ******
26
27 This manual is for Libffi, a portable foreign-function interface
28 library.
29
30    Copyright (C) 2008, 2010, 2011 Red Hat, Inc.
31
32      Permission is granted to copy, distribute and/or modify this
33      document under the terms of the GNU General Public License as
34      published by the Free Software Foundation; either version 2, or
35      (at your option) any later version.  A copy of the license is
36      included in the section entitled "GNU General Public License".
37
38
39 * Menu:
40
41 * Introduction::                What is libffi?
42 * Using libffi::                How to use libffi.
43 * Missing Features::            Things libffi can't do.
44 * Index::                       Index.
45
46 \1f
47 File: libffi.info,  Node: Introduction,  Next: Using libffi,  Prev: Top,  Up: Top
48
49 1 What is libffi?
50 *****************
51
52 Compilers for high level languages generate code that follow certain
53 conventions.  These conventions are necessary, in part, for separate
54 compilation to work.  One such convention is the "calling convention".
55 The calling convention is a set of assumptions made by the compiler
56 about where function arguments will be found on entry to a function.  A
57 calling convention also specifies where the return value for a function
58 is found.  The calling convention is also sometimes called the "ABI" or
59 "Application Binary Interface".  
60
61    Some programs may not know at the time of compilation what arguments
62 are to be passed to a function.  For instance, an interpreter may be
63 told at run-time about the number and types of arguments used to call a
64 given function.  `Libffi' can be used in such programs to provide a
65 bridge from the interpreter program to compiled code.
66
67    The `libffi' library provides a portable, high level programming
68 interface to various calling conventions.  This allows a programmer to
69 call any function specified by a call interface description at run time.
70
71    FFI stands for Foreign Function Interface.  A foreign function
72 interface is the popular name for the interface that allows code
73 written in one language to call code written in another language.  The
74 `libffi' library really only provides the lowest, machine dependent
75 layer of a fully featured foreign function interface.  A layer must
76 exist above `libffi' that handles type conversions for values passed
77 between the two languages.  
78
79 \1f
80 File: libffi.info,  Node: Using libffi,  Next: Missing Features,  Prev: Introduction,  Up: Top
81
82 2 Using libffi
83 **************
84
85 * Menu:
86
87 * The Basics::                  The basic libffi API.
88 * Simple Example::              A simple example.
89 * Types::                       libffi type descriptions.
90 * Multiple ABIs::               Different passing styles on one platform.
91 * The Closure API::             Writing a generic function.
92 * Closure Example::             A closure example.
93
94 \1f
95 File: libffi.info,  Node: The Basics,  Next: Simple Example,  Up: Using libffi
96
97 2.1 The Basics
98 ==============
99
100 `Libffi' assumes that you have a pointer to the function you wish to
101 call and that you know the number and types of arguments to pass it, as
102 well as the return type of the function.
103
104    The first thing you must do is create an `ffi_cif' object that
105 matches the signature of the function you wish to call.  This is a
106 separate step because it is common to make multiple calls using a
107 single `ffi_cif'.  The "cif" in `ffi_cif' stands for Call InterFace.
108 To prepare a call interface object, use the function `ffi_prep_cif'.  
109
110  -- Function: ffi_status ffi_prep_cif (ffi_cif *CIF, ffi_abi ABI,
111           unsigned int NARGS, ffi_type *RTYPE, ffi_type **ARGTYPES)
112      This initializes CIF according to the given parameters.
113
114      ABI is the ABI to use; normally `FFI_DEFAULT_ABI' is what you
115      want.  *note Multiple ABIs:: for more information.
116
117      NARGS is the number of arguments that this function accepts.
118
119      RTYPE is a pointer to an `ffi_type' structure that describes the
120      return type of the function.  *Note Types::.
121
122      ARGTYPES is a vector of `ffi_type' pointers.  ARGTYPES must have
123      NARGS elements.  If NARGS is 0, this argument is ignored.
124
125      `ffi_prep_cif' returns a `libffi' status code, of type
126      `ffi_status'.  This will be either `FFI_OK' if everything worked
127      properly; `FFI_BAD_TYPEDEF' if one of the `ffi_type' objects is
128      incorrect; or `FFI_BAD_ABI' if the ABI parameter is invalid.
129
130    If the function being called is variadic (varargs) then
131 `ffi_prep_cif_var' must be used instead of `ffi_prep_cif'.
132
133  -- Function: ffi_status ffi_prep_cif_var (ffi_cif *CIF, ffi_abi
134           varabi, unsigned int NFIXEDARGS, unsigned int varntotalargs,
135           ffi_type *RTYPE, ffi_type **ARGTYPES)
136      This initializes CIF according to the given parameters for a call
137      to a variadic function.  In general it's operation is the same as
138      for `ffi_prep_cif' except that:
139
140      NFIXEDARGS is the number of fixed arguments, prior to any variadic
141      arguments.  It must be greater than zero.
142
143      NTOTALARGS the total number of arguments, including variadic and
144      fixed arguments.
145
146      Note that, different cif's must be prepped for calls to the same
147      function when different numbers of arguments are passed.
148
149      Also note that a call to `ffi_prep_cif_var' with
150      NFIXEDARGS=NOTOTALARGS is NOT equivalent to a call to
151      `ffi_prep_cif'.
152
153
154    To call a function using an initialized `ffi_cif', use the
155 `ffi_call' function:
156
157  -- Function: void ffi_call (ffi_cif *CIF, void *FN, void *RVALUE, void
158           **AVALUES)
159      This calls the function FN according to the description given in
160      CIF.  CIF must have already been prepared using `ffi_prep_cif'.
161
162      RVALUE is a pointer to a chunk of memory that will hold the result
163      of the function call.  This must be large enough to hold the
164      result and must be suitably aligned; it is the caller's
165      responsibility to ensure this.  If CIF declares that the function
166      returns `void' (using `ffi_type_void'), then RVALUE is ignored.
167      If RVALUE is `NULL', then the return value is discarded.
168
169      AVALUES is a vector of `void *' pointers that point to the memory
170      locations holding the argument values for a call.  If CIF declares
171      that the function has no arguments (i.e., NARGS was 0), then
172      AVALUES is ignored.  Note that argument values may be modified by
173      the callee (for instance, structs passed by value); the burden of
174      copying pass-by-value arguments is placed on the caller.
175
176 \1f
177 File: libffi.info,  Node: Simple Example,  Next: Types,  Prev: The Basics,  Up: Using libffi
178
179 2.2 Simple Example
180 ==================
181
182 Here is a trivial example that calls `puts' a few times.
183
184      #include <stdio.h>
185      #include <ffi.h>
186
187      int main()
188      {
189        ffi_cif cif;
190        ffi_type *args[1];
191        void *values[1];
192        char *s;
193        int rc;
194
195        /* Initialize the argument info vectors */
196        args[0] = &ffi_type_pointer;
197        values[0] = &s;
198
199        /* Initialize the cif */
200        if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
201                        &ffi_type_uint, args) == FFI_OK)
202          {
203            s = "Hello World!";
204            ffi_call(&cif, puts, &rc, values);
205            /* rc now holds the result of the call to puts */
206
207            /* values holds a pointer to the function's arg, so to
208               call puts() again all we need to do is change the
209               value of s */
210            s = "This is cool!";
211            ffi_call(&cif, puts, &rc, values);
212          }
213
214        return 0;
215      }
216
217 \1f
218 File: libffi.info,  Node: Types,  Next: Multiple ABIs,  Prev: Simple Example,  Up: Using libffi
219
220 2.3 Types
221 =========
222
223 * Menu:
224
225 * Primitive Types::             Built-in types.
226 * Structures::                  Structure types.
227 * Type Example::                Structure type example.
228
229 \1f
230 File: libffi.info,  Node: Primitive Types,  Next: Structures,  Up: Types
231
232 2.3.1 Primitive Types
233 ---------------------
234
235 `Libffi' provides a number of built-in type descriptors that can be
236 used to describe argument and return types:
237
238 `ffi_type_void'
239      The type `void'.  This cannot be used for argument types, only for
240      return values.
241
242 `ffi_type_uint8'
243      An unsigned, 8-bit integer type.
244
245 `ffi_type_sint8'
246      A signed, 8-bit integer type.
247
248 `ffi_type_uint16'
249      An unsigned, 16-bit integer type.
250
251 `ffi_type_sint16'
252      A signed, 16-bit integer type.
253
254 `ffi_type_uint32'
255      An unsigned, 32-bit integer type.
256
257 `ffi_type_sint32'
258      A signed, 32-bit integer type.
259
260 `ffi_type_uint64'
261      An unsigned, 64-bit integer type.
262
263 `ffi_type_sint64'
264      A signed, 64-bit integer type.
265
266 `ffi_type_float'
267      The C `float' type.
268
269 `ffi_type_double'
270      The C `double' type.
271
272 `ffi_type_uchar'
273      The C `unsigned char' type.
274
275 `ffi_type_schar'
276      The C `signed char' type.  (Note that there is not an exact
277      equivalent to the C `char' type in `libffi'; ordinarily you should
278      either use `ffi_type_schar' or `ffi_type_uchar' depending on
279      whether `char' is signed.)
280
281 `ffi_type_ushort'
282      The C `unsigned short' type.
283
284 `ffi_type_sshort'
285      The C `short' type.
286
287 `ffi_type_uint'
288      The C `unsigned int' type.
289
290 `ffi_type_sint'
291      The C `int' type.
292
293 `ffi_type_ulong'
294      The C `unsigned long' type.
295
296 `ffi_type_slong'
297      The C `long' type.
298
299 `ffi_type_longdouble'
300      On platforms that have a C `long double' type, this is defined.
301      On other platforms, it is not.
302
303 `ffi_type_pointer'
304      A generic `void *' pointer.  You should use this for all pointers,
305      regardless of their real type.
306
307    Each of these is of type `ffi_type', so you must take the address
308 when passing to `ffi_prep_cif'.
309
310 \1f
311 File: libffi.info,  Node: Structures,  Next: Type Example,  Prev: Primitive Types,  Up: Types
312
313 2.3.2 Structures
314 ----------------
315
316 Although `libffi' has no special support for unions or bit-fields, it
317 is perfectly happy passing structures back and forth.  You must first
318 describe the structure to `libffi' by creating a new `ffi_type' object
319 for it.
320
321  -- ffi_type:
322      The `ffi_type' has the following members:
323     `size_t size'
324           This is set by `libffi'; you should initialize it to zero.
325
326     `unsigned short alignment'
327           This is set by `libffi'; you should initialize it to zero.
328
329     `unsigned short type'
330           For a structure, this should be set to `FFI_TYPE_STRUCT'.
331
332     `ffi_type **elements'
333           This is a `NULL'-terminated array of pointers to `ffi_type'
334           objects.  There is one element per field of the struct.
335
336 \1f
337 File: libffi.info,  Node: Type Example,  Prev: Structures,  Up: Types
338
339 2.3.3 Type Example
340 ------------------
341
342 The following example initializes a `ffi_type' object representing the
343 `tm' struct from Linux's `time.h'.
344
345    Here is how the struct is defined:
346
347      struct tm {
348          int tm_sec;
349          int tm_min;
350          int tm_hour;
351          int tm_mday;
352          int tm_mon;
353          int tm_year;
354          int tm_wday;
355          int tm_yday;
356          int tm_isdst;
357          /* Those are for future use. */
358          long int __tm_gmtoff__;
359          __const char *__tm_zone__;
360      };
361
362    Here is the corresponding code to describe this struct to `libffi':
363
364          {
365            ffi_type tm_type;
366            ffi_type *tm_type_elements[12];
367            int i;
368
369            tm_type.size = tm_type.alignment = 0;
370            tm_type.elements = &tm_type_elements;
371
372            for (i = 0; i < 9; i++)
373                tm_type_elements[i] = &ffi_type_sint;
374
375            tm_type_elements[9] = &ffi_type_slong;
376            tm_type_elements[10] = &ffi_type_pointer;
377            tm_type_elements[11] = NULL;
378
379            /* tm_type can now be used to represent tm argument types and
380          return types for ffi_prep_cif() */
381          }
382
383 \1f
384 File: libffi.info,  Node: Multiple ABIs,  Next: The Closure API,  Prev: Types,  Up: Using libffi
385
386 2.4 Multiple ABIs
387 =================
388
389 A given platform may provide multiple different ABIs at once.  For
390 instance, the x86 platform has both `stdcall' and `fastcall' functions.
391
392    `libffi' provides some support for this.  However, this is
393 necessarily platform-specific.
394
395 \1f
396 File: libffi.info,  Node: The Closure API,  Next: Closure Example,  Prev: Multiple ABIs,  Up: Using libffi
397
398 2.5 The Closure API
399 ===================
400
401 `libffi' also provides a way to write a generic function - a function
402 that can accept and decode any combination of arguments.  This can be
403 useful when writing an interpreter, or to provide wrappers for
404 arbitrary functions.
405
406    This facility is called the "closure API".  Closures are not
407 supported on all platforms; you can check the `FFI_CLOSURES' define to
408 determine whether they are supported on the current platform.  
409
410    Because closures work by assembling a tiny function at runtime, they
411 require special allocation on platforms that have a non-executable
412 heap.  Memory management for closures is handled by a pair of functions:
413
414  -- Function: void *ffi_closure_alloc (size_t SIZE, void **CODE)
415      Allocate a chunk of memory holding SIZE bytes.  This returns a
416      pointer to the writable address, and sets *CODE to the
417      corresponding executable address.
418
419      SIZE should be sufficient to hold a `ffi_closure' object.
420
421  -- Function: void ffi_closure_free (void *WRITABLE)
422      Free memory allocated using `ffi_closure_alloc'.  The argument is
423      the writable address that was returned.
424
425    Once you have allocated the memory for a closure, you must construct
426 a `ffi_cif' describing the function call.  Finally you can prepare the
427 closure function:
428
429  -- Function: ffi_status ffi_prep_closure_loc (ffi_closure *CLOSURE,
430           ffi_cif *CIF, void (*FUN) (ffi_cif *CIF, void *RET, void
431           **ARGS, void *USER_DATA), void *USER_DATA, void *CODELOC)
432      Prepare a closure function.
433
434      CLOSURE is the address of a `ffi_closure' object; this is the
435      writable address returned by `ffi_closure_alloc'.
436
437      CIF is the `ffi_cif' describing the function parameters.
438
439      USER_DATA is an arbitrary datum that is passed, uninterpreted, to
440      your closure function.
441
442      CODELOC is the executable address returned by `ffi_closure_alloc'.
443
444      FUN is the function which will be called when the closure is
445      invoked.  It is called with the arguments:
446     CIF
447           The `ffi_cif' passed to `ffi_prep_closure_loc'.
448
449     RET
450           A pointer to the memory used for the function's return value.
451           FUN must fill this, unless the function is declared as
452           returning `void'.
453
454     ARGS
455           A vector of pointers to memory holding the arguments to the
456           function.
457
458     USER_DATA
459           The same USER_DATA that was passed to `ffi_prep_closure_loc'.
460
461      `ffi_prep_closure_loc' will return `FFI_OK' if everything went ok,
462      and something else on error.
463
464      After calling `ffi_prep_closure_loc', you can cast CODELOC to the
465      appropriate pointer-to-function type.
466
467    You may see old code referring to `ffi_prep_closure'.  This function
468 is deprecated, as it cannot handle the need for separate writable and
469 executable addresses.
470
471 \1f
472 File: libffi.info,  Node: Closure Example,  Prev: The Closure API,  Up: Using libffi
473
474 2.6 Closure Example
475 ===================
476
477 A trivial example that creates a new `puts' by binding `fputs' with
478 `stdin'.
479
480      #include <stdio.h>
481      #include <ffi.h>
482
483      /* Acts like puts with the file given at time of enclosure. */
484      void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[],
485                        FILE *stream)
486      {
487        *ret = fputs(*(char **)args[0], stream);
488      }
489
490      int main()
491      {
492        ffi_cif cif;
493        ffi_type *args[1];
494        ffi_closure *closure;
495
496        int (*bound_puts)(char *);
497        int rc;
498
499        /* Allocate closure and bound_puts */
500        closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts);
501
502        if (closure)
503          {
504            /* Initialize the argument info vectors */
505            args[0] = &ffi_type_pointer;
506
507            /* Initialize the cif */
508            if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
509                             &ffi_type_uint, args) == FFI_OK)
510              {
511                /* Initialize the closure, setting stream to stdout */
512                if (ffi_prep_closure_loc(closure, &cif, puts_binding,
513                                         stdout, bound_puts) == FFI_OK)
514                  {
515                    rc = bound_puts("Hello World!");
516                    /* rc now holds the result of the call to fputs */
517                  }
518              }
519          }
520
521        /* Deallocate both closure, and bound_puts */
522        ffi_closure_free(closure);
523
524        return 0;
525      }
526
527 \1f
528 File: libffi.info,  Node: Missing Features,  Next: Index,  Prev: Using libffi,  Up: Top
529
530 3 Missing Features
531 ******************
532
533 `libffi' is missing a few features.  We welcome patches to add support
534 for these.
535
536    * Variadic closures.
537
538    * There is no support for bit fields in structures.
539
540    * The closure API is
541
542    * The "raw" API is undocumented.
543
544    Note that variadic support is very new and tested on a relatively
545 small number of platforms.
546
547 \1f
548 File: libffi.info,  Node: Index,  Prev: Missing Features,  Up: Top
549
550 Index
551 *****
552
553 \0\b[index\0\b]
554 * Menu:
555
556 * :                                      Structures.           (line 12)
557 * ABI:                                   Introduction.         (line 13)
558 * Application Binary Interface:          Introduction.         (line 13)
559 * calling convention:                    Introduction.         (line 13)
560 * cif:                                   The Basics.           (line 14)
561 * closure API:                           The Closure API.      (line 13)
562 * closures:                              The Closure API.      (line 13)
563 * FFI:                                   Introduction.         (line 31)
564 * ffi_call:                              The Basics.           (line 63)
565 * ffi_closure_alloc:                     The Closure API.      (line 19)
566 * ffi_closure_free:                      The Closure API.      (line 26)
567 * FFI_CLOSURES:                          The Closure API.      (line 13)
568 * ffi_prep_cif:                          The Basics.           (line 16)
569 * ffi_prep_cif_var:                      The Basics.           (line 39)
570 * ffi_prep_closure_loc:                  The Closure API.      (line 34)
571 * ffi_status <1>:                        The Closure API.      (line 37)
572 * ffi_status:                            The Basics.           (line 18)
573 * ffi_type:                              Structures.           (line 11)
574 * ffi_type_double:                       Primitive Types.      (line 41)
575 * ffi_type_float:                        Primitive Types.      (line 38)
576 * ffi_type_longdouble:                   Primitive Types.      (line 71)
577 * ffi_type_pointer:                      Primitive Types.      (line 75)
578 * ffi_type_schar:                        Primitive Types.      (line 47)
579 * ffi_type_sint:                         Primitive Types.      (line 62)
580 * ffi_type_sint16:                       Primitive Types.      (line 23)
581 * ffi_type_sint32:                       Primitive Types.      (line 29)
582 * ffi_type_sint64:                       Primitive Types.      (line 35)
583 * ffi_type_sint8:                        Primitive Types.      (line 17)
584 * ffi_type_slong:                        Primitive Types.      (line 68)
585 * ffi_type_sshort:                       Primitive Types.      (line 56)
586 * ffi_type_uchar:                        Primitive Types.      (line 44)
587 * ffi_type_uint:                         Primitive Types.      (line 59)
588 * ffi_type_uint16:                       Primitive Types.      (line 20)
589 * ffi_type_uint32:                       Primitive Types.      (line 26)
590 * ffi_type_uint64:                       Primitive Types.      (line 32)
591 * ffi_type_uint8:                        Primitive Types.      (line 14)
592 * ffi_type_ulong:                        Primitive Types.      (line 65)
593 * ffi_type_ushort:                       Primitive Types.      (line 53)
594 * ffi_type_void:                         Primitive Types.      (line 10)
595 * Foreign Function Interface:            Introduction.         (line 31)
596 * void <1>:                              The Closure API.      (line 20)
597 * void:                                  The Basics.           (line 65)
598
599
600 \1f
601 Tag Table:
602 Node: Top\7f712
603 Node: Introduction\7f1460
604 Node: Using libffi\7f3096
605 Node: The Basics\7f3582
606 Node: Simple Example\7f7224
607 Node: Types\7f8251
608 Node: Primitive Types\7f8534
609 Node: Structures\7f10354
610 Node: Type Example\7f11214
611 Node: Multiple ABIs\7f12437
612 Node: The Closure API\7f12808
613 Node: Closure Example\7f15752
614 Node: Missing Features\7f17311
615 Node: Index\7f17764
616 \1f
617 End Tag Table