diff options
Diffstat (limited to 'ext/ffi_c/libffi/doc/libffi.info')
| -rw-r--r-- | ext/ffi_c/libffi/doc/libffi.info | 593 |
1 files changed, 0 insertions, 593 deletions
diff --git a/ext/ffi_c/libffi/doc/libffi.info b/ext/ffi_c/libffi/doc/libffi.info deleted file mode 100644 index 449320c..0000000 --- a/ext/ffi_c/libffi/doc/libffi.info +++ /dev/null @@ -1,593 +0,0 @@ -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 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 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. - `libffi' does not yet handle varargs functions; see *note Missing - Features:: for more information. - - 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. - - 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. - - -- 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. - - * There is no support for calling varargs functions. This may work - on some platforms, depending on how the ABI is defined, but it is - not reliable. - - * There is no support for bit fields in structures. - - * The closure API is - - * The "raw" API is undocumented. - - -File: libffi.info, Node: Index, Prev: Missing Features, Up: Top - -Index -***** - - -* Menu: - -* : Structures. (line 12) -* 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 41) -* 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_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 43) - - - -Tag Table: -Node: Top706 -Node: Introduction1448 -Node: Using libffi3084 -Node: The Basics3570 -Node: Simple Example6356 -Node: Types7383 -Node: Primitive Types7666 -Node: Structures9486 -Node: Type Example10346 -Node: Multiple ABIs11569 -Node: The Closure API11940 -Node: Closure Example14884 -Node: Missing Features16443 -Node: Index16936 - -End Tag Table |