summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorAnthony Green <green@moxielogic.com>2013-10-08 06:27:46 -0400
committerAnthony Green <green@moxielogic.com>2013-10-08 06:27:46 -0400
commitd2fcbcdfbea750d1f6a9f493e2e6c4d5ffa71b34 (patch)
tree2e9b213eb56696938e20220c20c817d9ffa8b9c0 /doc
parentd3d099b40c122550279789200263346f120f6909 (diff)
downloadlibffi-d2fcbcdfbea750d1f6a9f493e2e6c4d5ffa71b34.tar.gz
Add m88k and VAX support. Update some configury bits.
Diffstat (limited to 'doc')
-rw-r--r--doc/libffi.info313
-rw-r--r--doc/stamp-vti8
-rw-r--r--doc/version.texi8
3 files changed, 164 insertions, 165 deletions
diff --git a/doc/libffi.info b/doc/libffi.info
index 6d5acf8..e57d345 100644
--- a/doc/libffi.info
+++ b/doc/libffi.info
@@ -1,5 +1,4 @@
-This is ../libffi/doc/libffi.info, produced by makeinfo version 4.13
-from ../libffi/doc/libffi.texi.
+This is libffi.info, produced by makeinfo version 5.1 from libffi.texi.
This manual is for Libffi, a portable foreign-function interface
library.
@@ -8,10 +7,9 @@ library.
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".
-
+ 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
@@ -31,10 +29,9 @@ library.
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".
-
+ 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:
@@ -56,25 +53,25 @@ 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".
+"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
+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
+ 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.
+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
@@ -97,45 +94,45 @@ 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
+'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
+ 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'.
+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.
+ 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
+ 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
+ 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.
+ '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'.
+'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)
+ -- 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:
+ for 'ffi_prep_cif' except that:
NFIXEDARGS is the number of fixed arguments, prior to any variadic
arguments. It must be greater than zero.
@@ -146,27 +143,26 @@ To prepare a call interface object, use the function `ffi_prep_cif'.
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
+ Also note that a call to 'ffi_prep_cif_var' with
NFIXEDARGS=NOTOTALARGS is NOT equivalent to a call to
- `ffi_prep_cif'.
-
+ 'ffi_prep_cif'.
- To call a function using an initialized `ffi_cif', use the
-`ffi_call' function:
+ 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'.
+ 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.
+ 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
+ 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
@@ -179,7 +175,7 @@ File: libffi.info, Node: Simple Example, Next: Types, Prev: The Basics, Up:
2.2 Simple Example
==================
-Here is a trivial example that calls `puts' a few times.
+Here is a trivial example that calls 'puts' a few times.
#include <stdio.h>
#include <ffi.h>
@@ -232,80 +228,80 @@ 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:
+'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
+'ffi_type_void'
+ The type 'void'. This cannot be used for argument types, only for
return values.
-`ffi_type_uint8'
+'ffi_type_uint8'
An unsigned, 8-bit integer type.
-`ffi_type_sint8'
+'ffi_type_sint8'
A signed, 8-bit integer type.
-`ffi_type_uint16'
+'ffi_type_uint16'
An unsigned, 16-bit integer type.
-`ffi_type_sint16'
+'ffi_type_sint16'
A signed, 16-bit integer type.
-`ffi_type_uint32'
+'ffi_type_uint32'
An unsigned, 32-bit integer type.
-`ffi_type_sint32'
+'ffi_type_sint32'
A signed, 32-bit integer type.
-`ffi_type_uint64'
+'ffi_type_uint64'
An unsigned, 64-bit integer type.
-`ffi_type_sint64'
+'ffi_type_sint64'
A signed, 64-bit integer type.
-`ffi_type_float'
- The C `float' type.
+'ffi_type_float'
+ The C 'float' type.
-`ffi_type_double'
- The C `double' type.
+'ffi_type_double'
+ The C 'double' type.
-`ffi_type_uchar'
- The C `unsigned char' 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_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_ushort'
+ The C 'unsigned short' type.
-`ffi_type_sshort'
- The C `short' type.
+'ffi_type_sshort'
+ The C 'short' type.
-`ffi_type_uint'
- The C `unsigned int' type.
+'ffi_type_uint'
+ The C 'unsigned int' type.
-`ffi_type_sint'
- The C `int' type.
+'ffi_type_sint'
+ The C 'int' type.
-`ffi_type_ulong'
- The C `unsigned long' type.
+'ffi_type_ulong'
+ The C 'unsigned long' type.
-`ffi_type_slong'
- The C `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_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,
+'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'.
+ 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
@@ -313,24 +309,24 @@ File: libffi.info, Node: Structures, Next: Type Example, Prev: Primitive Type
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
+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.
+ 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 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'.
+ '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'
+ 'ffi_type **elements'
+ This is a 'NULL'-terminated array of pointers to 'ffi_type'
objects. There is one element per field of the struct.

@@ -339,8 +335,8 @@ 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'.
+The following example initializes a 'ffi_type' object representing the
+'tm' struct from Linux's 'time.h'.
Here is how the struct is defined:
@@ -359,7 +355,7 @@ The following example initializes a `ffi_type' object representing the
__const char *__tm_zone__;
};
- Here is the corresponding code to describe this struct to `libffi':
+ Here is the corresponding code to describe this struct to 'libffi':
{
ffi_type tm_type;
@@ -387,9 +383,9 @@ File: libffi.info, Node: Multiple ABIs, Next: The Closure API, Prev: Types,
=================
A given platform may provide multiple different ABIs at once. For
-instance, the x86 platform has both `stdcall' and `fastcall' functions.
+instance, the x86 platform has both 'stdcall' and 'fastcall' functions.
- `libffi' provides some support for this. However, this is
+ 'libffi' provides some support for this. However, this is
necessarily platform-specific.

@@ -398,32 +394,32 @@ File: libffi.info, Node: The Closure API, Next: Closure Example, Prev: Multip
2.5 The Closure API
===================
-`libffi' also provides a way to write a generic function - a function
+'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.
+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.
+ 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:
+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.
+ 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
+ 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
+a 'ffi_cif' describing the function call. Finally you can prepare the
closure function:
-- Function: ffi_status ffi_prep_closure_loc (ffi_closure *CLOSURE,
@@ -431,40 +427,40 @@ closure function:
**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'.
+ 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.
+ 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'.
+ 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'.
+ CIF
+ The 'ffi_cif' passed to 'ffi_prep_closure_loc'.
- RET
+ 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'.
+ returning 'void'.
- ARGS
+ 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'.
+ 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,
+ '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
+ 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
+ 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.
@@ -474,8 +470,8 @@ File: libffi.info, Node: Closure Example, Prev: The Closure API, Up: Using li
2.6 Closure Example
===================
-A trivial example that creates a new `puts' by binding `fputs' with
-`stdin'.
+A trivial example that creates a new 'puts' by binding 'fputs' with
+'stdin'.
#include <stdio.h>
#include <ffi.h>
@@ -530,7 +526,7 @@ File: libffi.info, Node: Missing Features, Next: Index, Prev: Using libffi,
3 Missing Features
******************
-`libffi' is missing a few features. We welcome patches to add support
+'libffi' is missing a few features. We welcome patches to add support
for these.
* Variadic closures.
@@ -560,16 +556,18 @@ Index
* closure API: The Closure API. (line 13)
* closures: The Closure API. (line 13)
* FFI: Introduction. (line 31)
-* ffi_call: The Basics. (line 63)
+* ffi_call: The Basics. (line 62)
+* FFI_CLOSURES: The Closure API. (line 13)
* 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_status: The Basics. (line 16)
+* ffi_status <1>: The Basics. (line 39)
+* ffi_status <2>: The Closure API. (line 34)
* ffi_type: Structures. (line 11)
+* ffi_type <1>: Structures. (line 11)
* ffi_type_double: Primitive Types. (line 41)
* ffi_type_float: Primitive Types. (line 38)
* ffi_type_longdouble: Primitive Types. (line 71)
@@ -592,25 +590,26 @@ Index
* 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)
+* void: The Basics. (line 62)
+* void <1>: The Closure API. (line 19)
+* void <2>: The Closure API. (line 26)

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
+Node: Top682
+Node: Introduction1429
+Node: Using libffi3061
+Node: The Basics3547
+Node: Simple Example7187
+Node: Types8214
+Node: Primitive Types8497
+Node: Structures10318
+Node: Type Example11192
+Node: Multiple ABIs12415
+Node: The Closure API12786
+Node: Closure Example15730
+Node: Missing Features17289
+Node: Index17742

End Tag Table
diff --git a/doc/stamp-vti b/doc/stamp-vti
index 54255ba..fbdde9b 100644
--- a/doc/stamp-vti
+++ b/doc/stamp-vti
@@ -1,4 +1,4 @@
-@set UPDATED 16 March 2013
-@set UPDATED-MONTH March 2013
-@set EDITION 3.0.13
-@set VERSION 3.0.13
+@set UPDATED 2 July 2013
+@set UPDATED-MONTH July 2013
+@set EDITION 3.0.14-rc0
+@set VERSION 3.0.14-rc0
diff --git a/doc/version.texi b/doc/version.texi
index 54255ba..fbdde9b 100644
--- a/doc/version.texi
+++ b/doc/version.texi
@@ -1,4 +1,4 @@
-@set UPDATED 16 March 2013
-@set UPDATED-MONTH March 2013
-@set EDITION 3.0.13
-@set VERSION 3.0.13
+@set UPDATED 2 July 2013
+@set UPDATED-MONTH July 2013
+@set EDITION 3.0.14-rc0
+@set VERSION 3.0.14-rc0