| This is ../libffi/doc/libffi.info, produced by makeinfo version 4.13 |
| from ../libffi/doc/libffi.texi. |
| |
| This manual is for Libffi, a portable foreign-function interface |
| library. |
| |
| Copyright (C) 2008, 2010, 2011 Red Hat, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this |
| document under the terms of the GNU General Public License as |
| published by the Free Software Foundation; either version 2, or |
| (at your option) any later version. A copy of the license is |
| included in the section entitled "GNU General Public License". |
| |
| |
| INFO-DIR-SECTION Development |
| START-INFO-DIR-ENTRY |
| * libffi: (libffi). Portable foreign-function interface library. |
| END-INFO-DIR-ENTRY |
| |
| |
| File: libffi.info, Node: Top, Next: Introduction, Up: (dir) |
| |
| libffi |
| ****** |
| |
| This manual is for Libffi, a portable foreign-function interface |
| library. |
| |
| Copyright (C) 2008, 2010, 2011 Red Hat, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this |
| document under the terms of the GNU General Public License as |
| published by the Free Software Foundation; either version 2, or |
| (at your option) any later version. A copy of the license is |
| included in the section entitled "GNU General Public License". |
| |
| |
| * Menu: |
| |
| * Introduction:: What is libffi? |
| * Using libffi:: How to use libffi. |
| * Missing Features:: Things libffi can't do. |
| * Index:: Index. |
| |
| |
| File: libffi.info, Node: Introduction, Next: Using libffi, Prev: Top, Up: Top |
| |
| 1 What is libffi? |
| ***************** |
| |
| Compilers for high level languages generate code that follow certain |
| conventions. These conventions are necessary, in part, for separate |
| compilation to work. One such convention is the "calling convention". |
| The calling convention is a set of assumptions made by the compiler |
| about where function arguments will be found on entry to a function. A |
| calling convention also specifies where the return value for a function |
| is found. The calling convention is also sometimes called the "ABI" or |
| "Application Binary Interface". |
| |
| Some programs may not know at the time of compilation what arguments |
| are to be passed to a function. For instance, an interpreter may be |
| told at run-time about the number and types of arguments used to call a |
| given function. `Libffi' can be used in such programs to provide a |
| bridge from the interpreter program to compiled code. |
| |
| The `libffi' library provides a portable, high level programming |
| interface to various calling conventions. This allows a programmer to |
| call any function specified by a call interface description at run time. |
| |
| FFI stands for Foreign Function Interface. A foreign function |
| interface is the popular name for the interface that allows code |
| written in one language to call code written in another language. The |
| `libffi' library really only provides the lowest, machine dependent |
| layer of a fully featured foreign function interface. A layer must |
| exist above `libffi' that handles type conversions for values passed |
| between the two languages. |
| |
| |
| File: libffi.info, Node: Using libffi, Next: Missing Features, Prev: Introduction, Up: Top |
| |
| 2 Using libffi |
| ************** |
| |
| * Menu: |
| |
| * The Basics:: The basic libffi API. |
| * Simple Example:: A simple example. |
| * Types:: libffi type descriptions. |
| * Multiple ABIs:: Different passing styles on one platform. |
| * The Closure API:: Writing a generic function. |
| * Closure Example:: A closure example. |
| |
| |
| File: libffi.info, Node: The Basics, Next: Simple Example, Up: Using libffi |
| |
| 2.1 The Basics |
| ============== |
| |
| `Libffi' assumes that you have a pointer to the function you wish to |
| call and that you know the number and types of arguments to pass it, as |
| well as the return type of the function. |
| |
| The first thing you must do is create an `ffi_cif' object that |
| matches the signature of the function you wish to call. This is a |
| separate step because it is common to make multiple calls using a |
| single `ffi_cif'. The "cif" in `ffi_cif' stands for Call InterFace. |
| To prepare a call interface object, use the function `ffi_prep_cif'. |
| |
| -- Function: ffi_status ffi_prep_cif (ffi_cif *CIF, ffi_abi ABI, |
| unsigned int NARGS, ffi_type *RTYPE, ffi_type **ARGTYPES) |
| This initializes CIF according to the given parameters. |
| |
| ABI is the ABI to use; normally `FFI_DEFAULT_ABI' is what you |
| want. *note Multiple ABIs:: for more information. |
| |
| NARGS is the number of arguments that this function accepts. |
| |
| RTYPE is a pointer to an `ffi_type' structure that describes the |
| return type of the function. *Note Types::. |
| |
| ARGTYPES is a vector of `ffi_type' pointers. ARGTYPES must have |
| NARGS elements. If NARGS is 0, this argument is ignored. |
| |
| `ffi_prep_cif' returns a `libffi' status code, of type |
| `ffi_status'. This will be either `FFI_OK' if everything worked |
| properly; `FFI_BAD_TYPEDEF' if one of the `ffi_type' objects is |
| incorrect; or `FFI_BAD_ABI' if the ABI parameter is invalid. |
| |
| If the function being called is variadic (varargs) then |
| `ffi_prep_cif_var' must be used instead of `ffi_prep_cif'. |
| |
| -- Function: ffi_status ffi_prep_cif_var (ffi_cif *CIF, ffi_abi |
| varabi, unsigned int NFIXEDARGS, unsigned int varntotalargs, |
| ffi_type *RTYPE, ffi_type **ARGTYPES) |
| This initializes CIF according to the given parameters for a call |
| to a variadic function. In general it's operation is the same as |
| for `ffi_prep_cif' except that: |
| |
| NFIXEDARGS is the number of fixed arguments, prior to any variadic |
| arguments. It must be greater than zero. |
| |
| NTOTALARGS the total number of arguments, including variadic and |
| fixed arguments. |
| |
| Note that, different cif's must be prepped for calls to the same |
| function when different numbers of arguments are passed. |
| |
| Also note that a call to `ffi_prep_cif_var' with |
| NFIXEDARGS=NOTOTALARGS is NOT equivalent to a call to |
| `ffi_prep_cif'. |
| |
| |
| To call a function using an initialized `ffi_cif', use the |
| `ffi_call' function: |
| |
| -- Function: void ffi_call (ffi_cif *CIF, void *FN, void *RVALUE, void |
| **AVALUES) |
| This calls the function FN according to the description given in |
| CIF. CIF must have already been prepared using `ffi_prep_cif'. |
| |
| RVALUE is a pointer to a chunk of memory that will hold the result |
| of the function call. This must be large enough to hold the |
| result and must be suitably aligned; it is the caller's |
| responsibility to ensure this. If CIF declares that the function |
| returns `void' (using `ffi_type_void'), then RVALUE is ignored. |
| If RVALUE is `NULL', then the return value is discarded. |
| |
| AVALUES is a vector of `void *' pointers that point to the memory |
| locations holding the argument values for a call. If CIF declares |
| that the function has no arguments (i.e., NARGS was 0), then |
| AVALUES is ignored. Note that argument values may be modified by |
| the callee (for instance, structs passed by value); the burden of |
| copying pass-by-value arguments is placed on the caller. |
| |
| |
| File: libffi.info, Node: Simple Example, Next: Types, Prev: The Basics, Up: Using libffi |
| |
| 2.2 Simple Example |
| ================== |
| |
| Here is a trivial example that calls `puts' a few times. |
| |
| #include <stdio.h> |
| #include <ffi.h> |
| |
| int main() |
| { |
| ffi_cif cif; |
| ffi_type *args[1]; |
| void *values[1]; |
| char *s; |
| int rc; |
| |
| /* Initialize the argument info vectors */ |
| args[0] = &ffi_type_pointer; |
| values[0] = &s; |
| |
| /* Initialize the cif */ |
| if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, |
| &ffi_type_uint, args) == FFI_OK) |
| { |
| s = "Hello World!"; |
| ffi_call(&cif, puts, &rc, values); |
| /* rc now holds the result of the call to puts */ |
| |
| /* values holds a pointer to the function's arg, so to |
| call puts() again all we need to do is change the |
| value of s */ |
| s = "This is cool!"; |
| ffi_call(&cif, puts, &rc, values); |
| } |
| |
| return 0; |
| } |
| |
| |
| File: libffi.info, Node: Types, Next: Multiple ABIs, Prev: Simple Example, Up: Using libffi |
| |
| 2.3 Types |
| ========= |
| |
| * Menu: |
| |
| * Primitive Types:: Built-in types. |
| * Structures:: Structure types. |
| * Type Example:: Structure type example. |
| |
| |
| File: libffi.info, Node: Primitive Types, Next: Structures, Up: Types |
| |
| 2.3.1 Primitive Types |
| --------------------- |
| |
| `Libffi' provides a number of built-in type descriptors that can be |
| used to describe argument and return types: |
| |
| `ffi_type_void' |
| The type `void'. This cannot be used for argument types, only for |
| return values. |
| |
| `ffi_type_uint8' |
| An unsigned, 8-bit integer type. |
| |
| `ffi_type_sint8' |
| A signed, 8-bit integer type. |
| |
| `ffi_type_uint16' |
| An unsigned, 16-bit integer type. |
| |
| `ffi_type_sint16' |
| A signed, 16-bit integer type. |
| |
| `ffi_type_uint32' |
| An unsigned, 32-bit integer type. |
| |
| `ffi_type_sint32' |
| A signed, 32-bit integer type. |
| |
| `ffi_type_uint64' |
| An unsigned, 64-bit integer type. |
| |
| `ffi_type_sint64' |
| A signed, 64-bit integer type. |
| |
| `ffi_type_float' |
| The C `float' type. |
| |
| `ffi_type_double' |
| The C `double' type. |
| |
| `ffi_type_uchar' |
| The C `unsigned char' type. |
| |
| `ffi_type_schar' |
| The C `signed char' type. (Note that there is not an exact |
| equivalent to the C `char' type in `libffi'; ordinarily you should |
| either use `ffi_type_schar' or `ffi_type_uchar' depending on |
| whether `char' is signed.) |
| |
| `ffi_type_ushort' |
| The C `unsigned short' type. |
| |
| `ffi_type_sshort' |
| The C `short' type. |
| |
| `ffi_type_uint' |
| The C `unsigned int' type. |
| |
| `ffi_type_sint' |
| The C `int' type. |
| |
| `ffi_type_ulong' |
| The C `unsigned long' type. |
| |
| `ffi_type_slong' |
| The C `long' type. |
| |
| `ffi_type_longdouble' |
| On platforms that have a C `long double' type, this is defined. |
| On other platforms, it is not. |
| |
| `ffi_type_pointer' |
| A generic `void *' pointer. You should use this for all pointers, |
| regardless of their real type. |
| |
| Each of these is of type `ffi_type', so you must take the address |
| when passing to `ffi_prep_cif'. |
| |
| |
| File: libffi.info, Node: Structures, Next: Type Example, Prev: Primitive Types, Up: Types |
| |
| 2.3.2 Structures |
| ---------------- |
| |
| Although `libffi' has no special support for unions or bit-fields, it |
| is perfectly happy passing structures back and forth. You must first |
| describe the structure to `libffi' by creating a new `ffi_type' object |
| for it. |
| |
| -- Data type: ffi_type |
| The `ffi_type' has the following members: |
| `size_t size' |
| This is set by `libffi'; you should initialize it to zero. |
| |
| `unsigned short alignment' |
| This is set by `libffi'; you should initialize it to zero. |
| |
| `unsigned short type' |
| For a structure, this should be set to `FFI_TYPE_STRUCT'. |
| |
| `ffi_type **elements' |
| This is a `NULL'-terminated array of pointers to `ffi_type' |
| objects. There is one element per field of the struct. |
| |
| |
| File: libffi.info, Node: Type Example, Prev: Structures, Up: Types |
| |
| 2.3.3 Type Example |
| ------------------ |
| |
| The following example initializes a `ffi_type' object representing the |
| `tm' struct from Linux's `time.h'. |
| |
| Here is how the struct is defined: |
| |
| struct tm { |
| int tm_sec; |
| int tm_min; |
| int tm_hour; |
| int tm_mday; |
| int tm_mon; |
| int tm_year; |
| int tm_wday; |
| int tm_yday; |
| int tm_isdst; |
| /* Those are for future use. */ |
| long int __tm_gmtoff__; |
| __const char *__tm_zone__; |
| }; |
| |
| Here is the corresponding code to describe this struct to `libffi': |
| |
| { |
| ffi_type tm_type; |
| ffi_type *tm_type_elements[12]; |
| int i; |
| |
| tm_type.size = tm_type.alignment = 0; |
| tm_type.elements = &tm_type_elements; |
| |
| for (i = 0; i < 9; i++) |
| tm_type_elements[i] = &ffi_type_sint; |
| |
| tm_type_elements[9] = &ffi_type_slong; |
| tm_type_elements[10] = &ffi_type_pointer; |
| tm_type_elements[11] = NULL; |
| |
| /* tm_type can now be used to represent tm argument types and |
| return types for ffi_prep_cif() */ |
| } |
| |
| |
| File: libffi.info, Node: Multiple ABIs, Next: The Closure API, Prev: Types, Up: Using libffi |
| |
| 2.4 Multiple ABIs |
| ================= |
| |
| A given platform may provide multiple different ABIs at once. For |
| instance, the x86 platform has both `stdcall' and `fastcall' functions. |
| |
| `libffi' provides some support for this. However, this is |
| necessarily platform-specific. |
| |
| |
| File: libffi.info, Node: The Closure API, Next: Closure Example, Prev: Multiple ABIs, Up: Using libffi |
| |
| 2.5 The Closure API |
| =================== |
| |
| `libffi' also provides a way to write a generic function - a function |
| that can accept and decode any combination of arguments. This can be |
| useful when writing an interpreter, or to provide wrappers for |
| arbitrary functions. |
| |
| This facility is called the "closure API". Closures are not |
| supported on all platforms; you can check the `FFI_CLOSURES' define to |
| determine whether they are supported on the current platform. |
| |
| Because closures work by assembling a tiny function at runtime, they |
| require special allocation on platforms that have a non-executable |
| heap. Memory management for closures is handled by a pair of functions: |
| |
| -- Function: void *ffi_closure_alloc (size_t SIZE, void **CODE) |
| Allocate a chunk of memory holding SIZE bytes. This returns a |
| pointer to the writable address, and sets *CODE to the |
| corresponding executable address. |
| |
| SIZE should be sufficient to hold a `ffi_closure' object. |
| |
| -- Function: void ffi_closure_free (void *WRITABLE) |
| Free memory allocated using `ffi_closure_alloc'. The argument is |
| the writable address that was returned. |
| |
| Once you have allocated the memory for a closure, you must construct |
| a `ffi_cif' describing the function call. Finally you can prepare the |
| closure function: |
| |
| -- Function: ffi_status ffi_prep_closure_loc (ffi_closure *CLOSURE, |
| ffi_cif *CIF, void (*FUN) (ffi_cif *CIF, void *RET, void |
| **ARGS, void *USER_DATA), void *USER_DATA, void *CODELOC) |
| Prepare a closure function. |
| |
| CLOSURE is the address of a `ffi_closure' object; this is the |
| writable address returned by `ffi_closure_alloc'. |
| |
| CIF is the `ffi_cif' describing the function parameters. |
| |
| USER_DATA is an arbitrary datum that is passed, uninterpreted, to |
| your closure function. |
| |
| CODELOC is the executable address returned by `ffi_closure_alloc'. |
| |
| FUN is the function which will be called when the closure is |
| invoked. It is called with the arguments: |
| CIF |
| The `ffi_cif' passed to `ffi_prep_closure_loc'. |
| |
| RET |
| A pointer to the memory used for the function's return value. |
| FUN must fill this, unless the function is declared as |
| returning `void'. |
| |
| ARGS |
| A vector of pointers to memory holding the arguments to the |
| function. |
| |
| USER_DATA |
| The same USER_DATA that was passed to `ffi_prep_closure_loc'. |
| |
| `ffi_prep_closure_loc' will return `FFI_OK' if everything went ok, |
| and something else on error. |
| |
| After calling `ffi_prep_closure_loc', you can cast CODELOC to the |
| appropriate pointer-to-function type. |
| |
| You may see old code referring to `ffi_prep_closure'. This function |
| is deprecated, as it cannot handle the need for separate writable and |
| executable addresses. |
| |
| |
| File: libffi.info, Node: Closure Example, Prev: The Closure API, Up: Using libffi |
| |
| 2.6 Closure Example |
| =================== |
| |
| A trivial example that creates a new `puts' by binding `fputs' with |
| `stdin'. |
| |
| #include <stdio.h> |
| #include <ffi.h> |
| |
| /* Acts like puts with the file given at time of enclosure. */ |
| void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[], |
| FILE *stream) |
| { |
| *ret = fputs(*(char **)args[0], stream); |
| } |
| |
| int main() |
| { |
| ffi_cif cif; |
| ffi_type *args[1]; |
| ffi_closure *closure; |
| |
| int (*bound_puts)(char *); |
| int rc; |
| |
| /* Allocate closure and bound_puts */ |
| closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts); |
| |
| if (closure) |
| { |
| /* Initialize the argument info vectors */ |
| args[0] = &ffi_type_pointer; |
| |
| /* Initialize the cif */ |
| if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, |
| &ffi_type_uint, args) == FFI_OK) |
| { |
| /* Initialize the closure, setting stream to stdout */ |
| if (ffi_prep_closure_loc(closure, &cif, puts_binding, |
| stdout, bound_puts) == FFI_OK) |
| { |
| rc = bound_puts("Hello World!"); |
| /* rc now holds the result of the call to fputs */ |
| } |
| } |
| } |
| |
| /* Deallocate both closure, and bound_puts */ |
| ffi_closure_free(closure); |
| |
| return 0; |
| } |
| |
| |
| File: libffi.info, Node: Missing Features, Next: Index, Prev: Using libffi, Up: Top |
| |
| 3 Missing Features |
| ****************** |
| |
| `libffi' is missing a few features. We welcome patches to add support |
| for these. |
| |
| * Variadic closures. |
| |
| * There is no support for bit fields in structures. |
| |
| * The closure API is |
| |
| * The "raw" API is undocumented. |
| |
| Note that variadic support is very new and tested on a relatively |
| small number of platforms. |
| |
| |
| File: libffi.info, Node: Index, Prev: Missing Features, Up: Top |
| |
| Index |
| ***** |
| |
| �[index�] |
| * Menu: |
| |
| * ABI: Introduction. (line 13) |
| * Application Binary Interface: Introduction. (line 13) |
| * calling convention: Introduction. (line 13) |
| * cif: The Basics. (line 14) |
| * closure API: The Closure API. (line 13) |
| * closures: The Closure API. (line 13) |
| * FFI: Introduction. (line 31) |
| * ffi_call: The Basics. (line 63) |
| * ffi_closure_alloc: The Closure API. (line 19) |
| * ffi_closure_free: The Closure API. (line 26) |
| * FFI_CLOSURES: The Closure API. (line 13) |
| * ffi_prep_cif: The Basics. (line 16) |
| * ffi_prep_cif_var: The Basics. (line 39) |
| * ffi_prep_closure_loc: The Closure API. (line 34) |
| * ffi_status <1>: The Closure API. (line 37) |
| * ffi_status: The Basics. (line 18) |
| * ffi_type: Structures. (line 11) |
| * ffi_type_double: Primitive Types. (line 41) |
| * ffi_type_float: Primitive Types. (line 38) |
| * ffi_type_longdouble: Primitive Types. (line 71) |
| * ffi_type_pointer: Primitive Types. (line 75) |
| * ffi_type_schar: Primitive Types. (line 47) |
| * ffi_type_sint: Primitive Types. (line 62) |
| * ffi_type_sint16: Primitive Types. (line 23) |
| * ffi_type_sint32: Primitive Types. (line 29) |
| * ffi_type_sint64: Primitive Types. (line 35) |
| * ffi_type_sint8: Primitive Types. (line 17) |
| * ffi_type_slong: Primitive Types. (line 68) |
| * ffi_type_sshort: Primitive Types. (line 56) |
| * ffi_type_uchar: Primitive Types. (line 44) |
| * ffi_type_uint: Primitive Types. (line 59) |
| * ffi_type_uint16: Primitive Types. (line 20) |
| * ffi_type_uint32: Primitive Types. (line 26) |
| * ffi_type_uint64: Primitive Types. (line 32) |
| * ffi_type_uint8: Primitive Types. (line 14) |
| * ffi_type_ulong: Primitive Types. (line 65) |
| * ffi_type_ushort: Primitive Types. (line 53) |
| * ffi_type_void: Primitive Types. (line 10) |
| * Foreign Function Interface: Introduction. (line 31) |
| * void <1>: The Closure API. (line 20) |
| * void: The Basics. (line 65) |
| |
| |
| |
| Tag Table: |
| Node: Top712 |
| Node: Introduction1460 |
| Node: Using libffi3096 |
| Node: The Basics3582 |
| Node: Simple Example7224 |
| Node: Types8251 |
| Node: Primitive Types8534 |
| Node: Structures10354 |
| Node: Type Example11224 |
| Node: Multiple ABIs12447 |
| Node: The Closure API12818 |
| Node: Closure Example15762 |
| Node: Missing Features17321 |
| Node: Index17774 |
| |
| End Tag Table |
