From 1d1dc81104b209df3cfef0840735c59efae2f655 Mon Sep 17 00:00:00 2001 From: green Date: Thu, 14 Feb 2008 22:03:37 +0000 Subject: [PATCH] Add man files and info file. Update README. Tag as 2.99.3. --- libffi/ChangeLog.libffi | 17 ++ libffi/Makefile.am | 2 +- libffi/Makefile.in | 4 +- libffi/README | 288 ++++-------------- libffi/configure | 23 +- libffi/configure.ac | 4 +- libffi/doc/libffi.info | 533 ++++++++++++++++++++++++++++++++++ libffi/doc/stamp-vti | 4 + libffi/doc/version.texi | 4 +- libffi/man/Makefile.am | 8 + libffi/man/Makefile.in | 395 +++++++++++++++++++++++++ libffi/man/ffi.3 | 39 +++ libffi/man/ffi_call.3 | 103 +++++++ libffi/man/ffi_prep_cif.3 | 69 +++++ libffi/man/ffi_prep_closure.3 | 159 ++++++++++ 15 files changed, 1397 insertions(+), 255 deletions(-) create mode 100644 libffi/doc/libffi.info create mode 100644 libffi/doc/stamp-vti create mode 100644 libffi/man/Makefile.am create mode 100644 libffi/man/Makefile.in create mode 100644 libffi/man/ffi.3 create mode 100644 libffi/man/ffi_call.3 create mode 100644 libffi/man/ffi_prep_cif.3 create mode 100644 libffi/man/ffi_prep_closure.3 diff --git a/libffi/ChangeLog.libffi b/libffi/ChangeLog.libffi index 2a59cfc0..c16f2d2e 100644 --- a/libffi/ChangeLog.libffi +++ b/libffi/ChangeLog.libffi @@ -1,3 +1,20 @@ +2008-02-14 Anthony Green + + * README: Update. + * libffi.info: New file. + * doc/stamp-vti: New file. + * configure.ac: Bump version to 2.99.3. + * configure: Rebuilt. + +2008-02-14 Anthony Green + + * Makefile.am (SUBDIRS): Add man dir. + * Makefile.in: Rebuilt. + * configure.ac: Create Makefile. + * configure: Rebuilt. + * man/ffi_call.3 man/ffi_prep_cif.3 man/ffi_prep_closure.3 + man/Makefile.am man/Makefile.in: New files. + 2008-02-14 Tom Tromey * aclocal.m4, Makefile.in, configure, fficonfig.h.in: Rebuilt. diff --git a/libffi/Makefile.am b/libffi/Makefile.am index 96089210..610dabb0 100644 --- a/libffi/Makefile.am +++ b/libffi/Makefile.am @@ -2,7 +2,7 @@ AUTOMAKE_OPTIONS = foreign subdir-objects -SUBDIRS = include testsuite +SUBDIRS = include testsuite man EXTRA_DIST = LICENSE ChangeLog.v1 ChangeLog.libgcj configure.host \ src/alpha/ffi.c src/alpha/osf.S src/alpha/ffitarget.h \ diff --git a/libffi/Makefile.in b/libffi/Makefile.in index 593e104c..1fc2fada 100644 --- a/libffi/Makefile.in +++ b/libffi/Makefile.in @@ -60,7 +60,7 @@ subdir = . DIST_COMMON = README $(am__configure_deps) $(srcdir)/Makefile.am \ $(srcdir)/Makefile.in $(srcdir)/doc/stamp-vti \ $(srcdir)/doc/version.texi $(srcdir)/fficonfig.h.in \ - $(srcdir)/libffi.pc.in $(top_srcdir)/configure ChangeLog \ + $(srcdir)/libffi.pc.in $(top_srcdir)/configure ChangeLog TODO \ compile config.guess config.sub depcomp install-sh ltcf-c.sh \ ltcf-cxx.sh ltcf-gcj.sh ltconfig ltmain.sh mdate-sh missing \ mkinstalldirs texinfo.tex @@ -331,7 +331,7 @@ toolexeclibdir = @toolexeclibdir@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ AUTOMAKE_OPTIONS = foreign subdir-objects -SUBDIRS = include testsuite +SUBDIRS = include testsuite man EXTRA_DIST = LICENSE ChangeLog.v1 ChangeLog.libgcj configure.host \ src/alpha/ffi.c src/alpha/osf.S src/alpha/ffitarget.h \ src/arm/ffi.c src/arm/sysv.S src/arm/ffitarget.h \ diff --git a/libffi/README b/libffi/README index 56382bb3..6eacd9ce 100644 --- a/libffi/README +++ b/libffi/README @@ -36,38 +36,21 @@ exist above libffi that handles type conversions for values passed between the two languages. -Supported Platforms and Prerequisites -===================================== +Supported Platforms +=================== -Libffi has been ported to: - - SunOS 4.1.3 & Solaris 2.x (SPARC-V8, SPARC-V9) - - Irix 5.3 & 6.2 (System V/o32 & n32) - - Intel x86 - Linux (System V ABI) - - Alpha - Linux and OSF/1 - - m68k - Linux (System V ABI) - - PowerPC - Linux (System V ABI, Darwin, AIX) - - ARM - Linux (System V ABI) - -Libffi has been tested with the egcs 1.0.2 gcc compiler. Chances are -that other versions will work. Libffi has also been built and tested -with the SGI compiler tools. - -On PowerPC, the tests failed (see the note below). - -You must use GNU make to build libffi. SGI's make will not work. -Sun's probably won't either. - -If you port libffi to another platform, please let me know! I assume -that some will be easy (x86 NetBSD), and others will be more difficult -(HP). +Libffi has been ported to many different platforms, although this +release was only tested on: + arm oabi linux + arm eabi linux + hppa64 linux + powerpc64 linux + sparc solaris (SPARC V9 ABI) + x86 cygwin + x86 linux + x86-64 linux + Installing libffi ================= @@ -104,195 +87,6 @@ To ensure that libffi is working as advertised, type "make test". To install the library and header files, type "make install". -Using libffi -============ - - 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. The `cif' in ffi_cif -stands for Call InterFace. To prepare a call interface object, use the -following function: - -ffi_status ffi_prep_cif(ffi_cif *cif, ffi_abi abi, - unsigned int nargs, - ffi_type *rtype, ffi_type **atypes); - - CIF is a pointer to the call interface object you wish - to initialize. - - ABI is an enum that specifies the calling convention - to use for the call. FFI_DEFAULT_ABI defaults - to the system's native calling convention. Other - ABI's may be used with care. They are system - specific. - - NARGS is the number of arguments this function accepts. - libffi does not yet support vararg functions. - - RTYPE is a pointer to an ffi_type structure that represents - the return type of the function. Ffi_type objects - describe the types of values. libffi provides - ffi_type objects for many of the native C types: - signed int, unsigned int, signed char, unsigned char, - etc. There is also a pointer ffi_type object and - a void ffi_type. Use &ffi_type_void for functions that - don't return values. - - ATYPES is a vector of ffi_type pointers. ARGS must be NARGS long. - If NARGS is 0, this is ignored. - - -ffi_prep_cif will return a status code that you are responsible -for checking. It will be one of the following: - - FFI_OK - All is good. - - FFI_BAD_TYPEDEF - One of the ffi_type objects that ffi_prep_cif - came across is bad. - - -Before making the call, the VALUES vector should be initialized -with pointers to the appropriate argument values. - -To call the the function using the initialized ffi_cif, use the -ffi_call function: - -void ffi_call(ffi_cif *cif, void *fn, void *rvalue, void **avalues); - - CIF is a pointer to the ffi_cif initialized specifically - for this function. - - FN is a pointer to the function you want to call. - - RVALUE is a pointer to a chunk of memory that is to hold the - result of the function call. Currently, it must be - at least one word in size (except for the n32 version - under Irix 6.x, which must be a pointer to an 8 byte - aligned value (a long long). It must also be at least - word aligned (depending on the return type, and the - system's alignment requirements). If RTYPE is - &ffi_type_void, this is ignored. If RVALUE is NULL, - the return value is discarded. - - AVALUES is a vector of void* that point to the memory locations - holding the argument values for a call. - If NARGS is 0, this is ignored. - - -If you are expecting a return value from FN it will have been stored -at RVALUE. - - - - An Example - ---------- - -Here is a trivial example that calls puts() a few times. - - #include - #include - - 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; - } - - - - Aggregate Types - --------------- - -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. Here is the definition of ffi_type: - - typedef struct _ffi_type - { - unsigned size; - short alignment; - short type; - struct _ffi_type **elements; - } ffi_type; - -All structures must have type set to FFI_TYPE_STRUCT. You may set -size and alignment to 0. These will be calculated and reset to the -appropriate values by ffi_prep_cif(). - -elements is a NULL terminated array of pointers to ffi_type objects -that describe the type of the structure elements. These may, in turn, -be structure elements. - -The following example initializes a ffi_type object representing the -tm struct from Linux's time.h: - - 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__; - }; - - { - 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() */ - } - - - Platform Specific Notes ======================= @@ -340,8 +134,6 @@ You must use GNU Make to build libffi on SGI platforms. The ARM port was performed on a NetWinder running ARM Linux ELF (2.0.31) and gcc 2.8.1. - - PowerPC System V ABI -------------------- @@ -372,6 +164,9 @@ History 3.00 Feb-XX-08 Many changes, mostly thanks to the GCC project. + Cygnus Solutions is now Red Hat. + + [10 years go by...] 1.20 Oct-5-98 Raffaele Sena produces ARM port. @@ -456,34 +251,53 @@ History Authors & Credits ================= -libffi was written by Anthony Green . +libffi was originally written by Anthony Green . -Portions of libffi were derived from Gianni Mariani's free gencall -library for Silicon Graphics machines. +The developers of the GNU Compiler Collection project have made +innumerable valuable contributions. See the ChangeLog file for +details. + +Some of the ideas behind libffi were inspired by Gianni Mariani's free +gencall library for Silicon Graphics machines. The closure mechanism was designed and implemented by Kresten Krab Thorup. -The Sparc port was derived from code contributed by the fine folks at -Visible Decisions Inc . Further enhancements were -made by Gordon Irlam at Cygnus Solutions . +Major processor architecture ports were contributed by the following +developers: -The Alpha port was written by Richard Henderson at Cygnus Solutions. - -Andreas Schwab ported libffi to m68k Linux and provided a number of -bug fixes. - -Geoffrey Keating ported libffi to the PowerPC. - -Raffaele Sena ported libffi to the ARM. +alpha Richard Henderson +arm Raffaele Sena +cris Simon Posnjak, Hans-Peter Nilsson +frv Anthony Green +ia64 Hans Boehm +m32r Kazuhiro Inaoka +m68k Andreas Schwab +mips Anthony Green +mips64 David Daney +pa Randolph Chung +powerpc Geoffrey Keating +powerpc64 Jakub Jelinek +s390 Gerhard Tonn, Ulrich Weigand +sh Kaz Kojima +sh64 Kaz Kojima +sparc Anthony Green, Gordon Irlam +x86 Anthony Green +x86-64 Bo Thorsen Jesper Skov and Andrew Haley both did more than their fair share of stepping through the code and tracking down bugs. -Thanks also to Tom Tromey for bug fixes and configuration help. +Thanks also to Tom Tromey for bug fixes, documentation and +configuration help. Thanks to Jim Blandy, who provided some useful feedback on the libffi interface. +Andreas Tobler has done a tremendous amount of work on the testsuite. + +The list above is almost certainly incomplete and inaccurate. I'm +happy to make corrections or additions upon request. + If you have a problem, or have found a bug, please send a note to -green@cygnus.com. +green@redhat.com. diff --git a/libffi/configure b/libffi/configure index 8e01b264..9533dc19 100755 --- a/libffi/configure +++ b/libffi/configure @@ -1,6 +1,6 @@ #! /bin/sh # Guess values for system-dependent variables and create Makefiles. -# Generated by GNU Autoconf 2.61 for libffi 2.99.2. +# Generated by GNU Autoconf 2.61 for libffi 2.99.3. # # Report bugs to . # @@ -728,8 +728,8 @@ SHELL=${CONFIG_SHELL-/bin/sh} # Identity of this package. PACKAGE_NAME='libffi' PACKAGE_TARNAME='libffi' -PACKAGE_VERSION='2.99.2' -PACKAGE_STRING='libffi 2.99.2' +PACKAGE_VERSION='2.99.3' +PACKAGE_STRING='libffi 2.99.3' PACKAGE_BUGREPORT='http://gcc.gnu.org/bugs.html' # Factoring default headers for most tests. @@ -1457,7 +1457,7 @@ if test "$ac_init_help" = "long"; then # Omit some internal or obsolete options to make the list less imposing. # This message is too long to be a string in the A/UX 3.1 sh. cat <<_ACEOF -\`configure' configures libffi 2.99.2 to adapt to many kinds of systems. +\`configure' configures libffi 2.99.3 to adapt to many kinds of systems. Usage: $0 [OPTION]... [VAR=VALUE]... @@ -1528,7 +1528,7 @@ fi if test -n "$ac_init_help"; then case $ac_init_help in - short | recursive ) echo "Configuration of libffi 2.99.2:";; + short | recursive ) echo "Configuration of libffi 2.99.3:";; esac cat <<\_ACEOF @@ -1638,7 +1638,7 @@ fi test -n "$ac_init_help" && exit $ac_status if $ac_init_version; then cat <<\_ACEOF -libffi configure 2.99.2 +libffi configure 2.99.3 generated by GNU Autoconf 2.61 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, @@ -1652,7 +1652,7 @@ cat >config.log <<_ACEOF This file contains any messages produced by compilers while running configure, to aid debugging if configure makes a mistake. -It was created by libffi $as_me 2.99.2, which was +It was created by libffi $as_me 2.99.3, which was generated by GNU Autoconf 2.61. Invocation command line was $ $0 $@ @@ -2475,7 +2475,7 @@ fi # Define the identity of the package. PACKAGE='libffi' - VERSION='2.99.2' + VERSION='2.99.3' cat >>confdefs.h <<_ACEOF @@ -22695,7 +22695,7 @@ ac_config_commands="$ac_config_commands src" ac_config_links="$ac_config_links include/ffitarget.h:src/$TARGETDIR/ffitarget.h" -ac_config_files="$ac_config_files include/Makefile include/ffi.h Makefile testsuite/Makefile libffi.pc" +ac_config_files="$ac_config_files include/Makefile include/ffi.h Makefile testsuite/Makefile man/Makefile libffi.pc" cat >confcache <<\_ACEOF @@ -23297,7 +23297,7 @@ exec 6>&1 # report actual input values of CONFIG_FILES etc. instead of their # values after options handling. ac_log=" -This file was extended by libffi $as_me 2.99.2, which was +This file was extended by libffi $as_me 2.99.3, which was generated by GNU Autoconf 2.61. Invocation command line was CONFIG_FILES = $CONFIG_FILES @@ -23354,7 +23354,7 @@ Report bugs to ." _ACEOF cat >>$CONFIG_STATUS <<_ACEOF ac_cs_version="\\ -libffi config.status 2.99.2 +libffi config.status 2.99.3 configured by $0, generated by GNU Autoconf 2.61, with options \\"`echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`\\" @@ -23478,6 +23478,7 @@ do "include/ffi.h") CONFIG_FILES="$CONFIG_FILES include/ffi.h" ;; "Makefile") CONFIG_FILES="$CONFIG_FILES Makefile" ;; "testsuite/Makefile") CONFIG_FILES="$CONFIG_FILES testsuite/Makefile" ;; + "man/Makefile") CONFIG_FILES="$CONFIG_FILES man/Makefile" ;; "libffi.pc") CONFIG_FILES="$CONFIG_FILES libffi.pc" ;; *) { { echo "$as_me:$LINENO: error: invalid argument: $ac_config_target" >&5 diff --git a/libffi/configure.ac b/libffi/configure.ac index 66e6c184..14d3a3c3 100644 --- a/libffi/configure.ac +++ b/libffi/configure.ac @@ -2,7 +2,7 @@ dnl Process this with autoconf to create configure AC_PREREQ(2.59) -AC_INIT([libffi], [2.99.2], [http://gcc.gnu.org/bugs.html]) +AC_INIT([libffi], [2.99.3], [http://gcc.gnu.org/bugs.html]) AC_CONFIG_HEADERS([fficonfig.h]) AC_CANONICAL_SYSTEM @@ -352,6 +352,6 @@ test -d src/$TARGETDIR || mkdir src/$TARGETDIR AC_CONFIG_LINKS(include/ffitarget.h:src/$TARGETDIR/ffitarget.h) -AC_CONFIG_FILES(include/Makefile include/ffi.h Makefile testsuite/Makefile libffi.pc) +AC_CONFIG_FILES(include/Makefile include/ffi.h Makefile testsuite/Makefile man/Makefile libffi.pc) AC_OUTPUT diff --git a/libffi/doc/libffi.info b/libffi/doc/libffi.info new file mode 100644 index 00000000..dc7f02cf --- /dev/null +++ b/libffi/doc/libffi.info @@ -0,0 +1,533 @@ +This is ../libffi/doc/libffi.info, produced by makeinfo version 4.11 +from ../libffi/doc/libffi.texi. + +This manual is for Libffi, a portable foreign-function interface +library. + + Copyright (C) 2008 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 +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 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. + + +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. + + +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 + #include + + 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, 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: 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 +***** + +[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_alloca: 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: Top688 +Node: Introduction1424 +Node: Using libffi3060 +Node: The Basics3495 +Node: Simple Example6102 +Node: Types7129 +Node: Primitive Types7412 +Node: Structures9232 +Node: Type Example10092 +Node: Multiple ABIs11315 +Node: The Closure API11686 +Node: Missing Features14606 +Node: Index15099 + +End Tag Table diff --git a/libffi/doc/stamp-vti b/libffi/doc/stamp-vti new file mode 100644 index 00000000..b45fbb12 --- /dev/null +++ b/libffi/doc/stamp-vti @@ -0,0 +1,4 @@ +@set UPDATED 14 February 2008 +@set UPDATED-MONTH February 2008 +@set EDITION 2.99.3 +@set VERSION 2.99.3 diff --git a/libffi/doc/version.texi b/libffi/doc/version.texi index 3ce13b5a..b45fbb12 100644 --- a/libffi/doc/version.texi +++ b/libffi/doc/version.texi @@ -1,4 +1,4 @@ @set UPDATED 14 February 2008 @set UPDATED-MONTH February 2008 -@set EDITION 2.99.2 -@set VERSION 2.99.2 +@set EDITION 2.99.3 +@set VERSION 2.99.3 diff --git a/libffi/man/Makefile.am b/libffi/man/Makefile.am new file mode 100644 index 00000000..cd9e9848 --- /dev/null +++ b/libffi/man/Makefile.am @@ -0,0 +1,8 @@ +## Process this with automake to create Makefile.in + +AUTOMAKE_OPTIONS=foreign + +EXTRA_DIST = ffi.3 ffi_call.3 ffi_prep_cif.3 ffi_prep_closure.3 + +man_MANS = ffi.3 ffi_call.3 ffi_prep_cif.3 ffi_prep_closure.3 + diff --git a/libffi/man/Makefile.in b/libffi/man/Makefile.in new file mode 100644 index 00000000..66a6fa88 --- /dev/null +++ b/libffi/man/Makefile.in @@ -0,0 +1,395 @@ +# Makefile.in generated by automake 1.10 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +target_triplet = @target@ +subdir = man +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs +CONFIG_HEADER = $(top_builddir)/fficonfig.h +CONFIG_CLEAN_FILES = +SOURCES = +DIST_SOURCES = +man3dir = $(mandir)/man3 +am__installdirs = "$(DESTDIR)$(man3dir)" +NROFF = nroff +MANS = $(man_MANS) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ALLOCA = @ALLOCA@ +AMTAR = @AMTAR@ +AM_RUNTESTFLAGS = @AM_RUNTESTFLAGS@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCAS = @CCAS@ +CCASDEPMODE = @CCASDEPMODE@ +CCASFLAGS = @CCASFLAGS@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +ECHO = @ECHO@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +F77 = @F77@ +FFLAGS = @FFLAGS@ +GREP = @GREP@ +HAVE_LONG_DOUBLE = @HAVE_LONG_DOUBLE@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MKDIR_P = @MKDIR_P@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +TARGET = @TARGET@ +TARGETDIR = @TARGETDIR@ +VERSION = @VERSION@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_F77 = @ac_ct_F77@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target = @target@ +target_alias = @target_alias@ +target_cpu = @target_cpu@ +target_os = @target_os@ +target_vendor = @target_vendor@ +toolexecdir = @toolexecdir@ +toolexeclibdir = @toolexeclibdir@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +AUTOMAKE_OPTIONS = foreign +EXTRA_DIST = ffi.3 ffi_call.3 ffi_prep_cif.3 ffi_prep_closure.3 +man_MANS = ffi.3 ffi_call.3 ffi_prep_cif.3 ffi_prep_closure.3 +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign man/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --foreign man/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-man3: $(man3_MANS) $(man_MANS) + @$(NORMAL_INSTALL) + test -z "$(man3dir)" || $(MKDIR_P) "$(DESTDIR)$(man3dir)" + @list='$(man3_MANS) $(dist_man3_MANS) $(nodist_man3_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.3*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ + else file=$$i; fi; \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 3*) ;; \ + *) ext='3' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man3dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man3dir)/$$inst"; \ + done +uninstall-man3: + @$(NORMAL_UNINSTALL) + @list='$(man3_MANS) $(dist_man3_MANS) $(nodist_man3_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.3*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 3*) ;; \ + *) ext='3' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " rm -f '$(DESTDIR)$(man3dir)/$$inst'"; \ + rm -f "$(DESTDIR)$(man3dir)/$$inst"; \ + done +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(MANS) +installdirs: + for dir in "$(DESTDIR)$(man3dir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +info: info-am + +info-am: + +install-data-am: install-man + +install-dvi: install-dvi-am + +install-exec-am: + +install-html: install-html-am + +install-info: install-info-am + +install-man: install-man3 + +install-pdf: install-pdf-am + +install-ps: install-ps-am + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-man + +uninstall-man: uninstall-man3 + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + distclean distclean-generic distclean-libtool distdir dvi \ + dvi-am html html-am info info-am install install-am \ + install-data install-data-am install-dvi install-dvi-am \ + install-exec install-exec-am install-html install-html-am \ + install-info install-info-am install-man install-man3 \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + uninstall uninstall-am uninstall-man uninstall-man3 + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/libffi/man/ffi.3 b/libffi/man/ffi.3 new file mode 100644 index 00000000..8235b82c --- /dev/null +++ b/libffi/man/ffi.3 @@ -0,0 +1,39 @@ +.Dd July 20, 2007 +.Dt FFI 3 +.Sh NAME +.Nm FFI +.Nd Foreign Function Interface +.Sh LIBRARY +libffi, -lffi +.Sh SYNOPSIS +.In ffi.h +.Ft ffi_status +.Fo ffi_prep_cif +.Fa "ffi_cif *cif" +.Fa "ffi_abi abi" +.Fa "unsigned int nargs" +.Fa "ffi_type *rtype" +.Fa "ffi_type **atypes" +.Fc +.Ft ffi_status +.Fo ffi_prep_closure +.Fa "ffi_closure *closure" +.Fa "ffi_cif *cif" +.Fa "void (*fun)(ffi_cif*,void*,void**,void*)" +.Fa "void *user_data" +.Fc +.Ft void +.Fo ffi_call +.Fa "ffi_cif *cif" +.Fa "void (*fn)(void)" +.Fa "void *rvalue" +.Fa "void **avalue" +.Fc +.Sh DESCRIPTION +The foreign function interface provides a mechanism by which a function can +generate a call to another function at runtime without requiring knowledge of +the called function's interface at compile time. +.Sh SEE ALSO +.Xr ffi_prep_cif 3 , +.Xr ffi_prep_closure 3 , +.Xr ffi_call 3 diff --git a/libffi/man/ffi_call.3 b/libffi/man/ffi_call.3 new file mode 100644 index 00000000..48efe131 --- /dev/null +++ b/libffi/man/ffi_call.3 @@ -0,0 +1,103 @@ +.Dd July 20, 2007 +.Dt ffi_call 3 +.Sh NAME +.Nm ffi_call +.Nd Invoke a foreign function. +.Sh SYNOPSIS +.In ffi.h +.Ft void +.Fo ffi_call +.Fa "ffi_cif *cif" +.Fa "void (*fn)(void)" +.Fa "void *rvalue" +.Fa "void **avalue" +.Fc +.Sh DESCRIPTION +The +.Nm ffi_call +function provides a simple mechanism for invoking a function without +requiring knowledge of the function's interface at compile time. +.Fa fn +is called with the values retrieved from the pointers in the +.Fa avalue +array. The return value from +.Fa fn +is placed in storage pointed to by +.Fa rvalue . +.Fa cif +contains information describing the data types, sizes and alignments of the +arguments to and return value from +.Fa fn , +and must be initialized with +.Nm ffi_prep_cif +before it is used with +.Nm ffi_call . +.Pp +.Fa rvalue +must point to storage that is sizeof(long) or larger. For smaller +return value sizes, the +.Nm ffi_arg +or +.Nm ffi_sarg +integral type must be used to hold +the return value. +.Sh EXAMPLES +.Bd -literal +#include +#include + +unsigned char +foo(unsigned int, float); + +int +main(int argc, const char **argv) +{ + ffi_cif cif; + ffi_type *arg_types[2]; + void *arg_values[2]; + ffi_status status; + + // Because the return value from foo() is smaller than sizeof(long), it + // must be passed as ffi_arg or ffi_sarg. + ffi_arg result; + + // Specify the data type of each argument. Available types are defined + // in . + arg_types[0] = &ffi_type_uint; + arg_types[1] = &ffi_type_float; + + // Prepare the ffi_cif structure. + if ((status = ffi_prep_cif(&cif, FFI_DEFAULT_ABI, + 2, &ffi_type_uint8, arg_types)) != FFI_OK) + { + // Handle the ffi_status error. + } + + // Specify the values of each argument. + unsigned int arg1 = 42; + float arg2 = 5.1; + + arg_values[0] = &arg1; + arg_values[1] = &arg2; + + // Invoke the function. + ffi_call(&cif, FFI_FN(foo), &result, arg_values); + + // The ffi_arg 'result' now contains the unsigned char returned from foo(), + // which can be accessed by a typecast. + printf("result is %hhu", (unsigned char)result); + + return 0; +} + +// The target function. +unsigned char +foo(unsigned int x, float y) +{ + unsigned char result = x - y; + return result; +} +.Ed +.Sh SEE ALSO +.Xr ffi 3 , +.Xr ffi_prep_cif 3 diff --git a/libffi/man/ffi_prep_cif.3 b/libffi/man/ffi_prep_cif.3 new file mode 100644 index 00000000..87e7792e --- /dev/null +++ b/libffi/man/ffi_prep_cif.3 @@ -0,0 +1,69 @@ +.Dd July 20, 2007 +.Dt ffi_prep_cif 3 +.Sh NAME +.Nm ffi_prep_cif +.Nd Prepare a +.Nm ffi_cif +structure for use with +.Nm ffi_call +or +.Nm ffi_prep_closure . +.Sh SYNOPSIS +.In ffi.h +.Ft ffi_status +.Fo ffi_prep_cif +.Fa "ffi_cif *cif" +.Fa "ffi_abi abi" +.Fa "unsigned int nargs" +.Fa "ffi_type *rtype" +.Fa "ffi_type **atypes" +.Fc +.Sh DESCRIPTION +The +.Nm ffi_prep_cif +function prepares a +.Nm ffi_cif +structure for use with +.Nm ffi_call +or +.Nm ffi_prep_closure . +.Fa abi +specifies a set of calling conventions to use. +.Fa atypes +is an array of +.Fa nargs +pointers to +.Nm ffi_type +structs that describe the data type, size and alignment of each argument. +.Fa rtype +points to an +.Nm ffi_type +that describes the data type, size and alignment of the +return value. +.Sh RETURN VALUES +Upon successful completion, +.Nm ffi_prep_cif +returns +.Nm FFI_OK . +It will return +.Nm FFI_BAD_TYPEDEF +if +.Fa cif +is +.Nm NULL +or +.Fa atypes +or +.Fa rtype +is malformed. If +.Fa abi +does not refer to a valid ABI, +.Nm FFI_BAD_ABI +will be returned. Available ABIs are +defined in +.Nm +. +.Sh SEE ALSO +.Xr ffi 3 , +.Xr ffi_call 3 , +.Xr ffi_prep_closure 3 diff --git a/libffi/man/ffi_prep_closure.3 b/libffi/man/ffi_prep_closure.3 new file mode 100644 index 00000000..186a8d7b --- /dev/null +++ b/libffi/man/ffi_prep_closure.3 @@ -0,0 +1,159 @@ +.Dd July 20, 2007 +.Dt ffi_prep_closure 3 +.Sh NAME +.Nm ffi_prep_closure +.Nd Prepare a +.Nm ffi_closure +for execution. +.Sh SYNOPSIS +.In ffi.h +.Ft ffi_status +.Fo ffi_prep_closure +.Fa "ffi_closure *closure" +.Fa "ffi_cif *cif" +.Fa "void (*fun)(ffi_cif*,void*,void**,void*)" +.Fa "void *user_data" +.Fc +.Sh DESCRIPTION +.Fa closure +is prepared to execute +.Fa fun . +.Fa cif +contains information describing the data types, sizes and alignments of the +arguments to and return value from the function that will be called from +.Fa fun , +and must be initialized with +.Nm ffi_prep_cif +before it is used with +.Nm ffi_prep_closure . +.Fa user_data +may point to additional data to be used in +.Fa fun . +If no additional data is needed, +.Fa user_data +may be +.Nm NULL . +When +.Fa closure +is invoked, +.Fa fun +is called with +.Fa cif , +an array of pointers to arguments, a pointer to a return value, and +.Fa user_data . +.Pp +Some architectures do not allow the execution of data by default. In such cases, +it is necessary to manually alter the permissions of the page that contains +.Fa closure +prior to its execution. +.Sh RETURN VALUES +Upon successful completion, +.Nm ffi_prep_closure +returns +.Nm FFI_OK . +If the ABI specified in +.Fa cif +does not refer to a valid ABI, +.Nm FFI_BAD_ABI +will be returned. Available ABIs are +defined in +.Nm +and +.Nm . +.Sh EXAMPLES +.Bd -literal +#include +#include // for mmap() + +unsigned char +foo(unsigned int, float); + +static void +foo_closure(ffi_cif*, void*, void**, void*); + +int +main(int argc, const char **argv) +{ + ffi_cif cif; + ffi_closure *closure; + ffi_type *arg_types[2]; + ffi_arg result; + ffi_status status; + + // Specify the data type of each argument. Available types are defined + // in . + arg_types[0] = &ffi_type_uint; + arg_types[1] = &ffi_type_float; + + // Allocate a page to hold the closure with read and write permissions. + if ((closure = mmap(NULL, sizeof(ffi_closure), PROT_READ | PROT_WRITE, + MAP_ANON | MAP_PRIVATE, -1, 0)) == (void*)-1) + { + // Check errno and handle the error. + } + + // Prepare the ffi_cif structure. + if ((status = ffi_prep_cif(&cif, FFI_DEFAULT_ABI, + 2, &ffi_type_uint8, arg_types)) != FFI_OK) + { + // Handle the ffi_status error. + } + + // Prepare the ffi_closure structure. + if ((status = ffi_prep_closure(closure, &cif, foo_closure, NULL)) != FFI_OK) + { + // Handle the ffi_status error. + } + + // Ensure that the closure will execute on all architectures. + if (mprotect(closure, sizeof(closure), PROT_READ | PROT_EXEC) == -1) + { + // Check errno and handle the error. + } + + // The closure is now ready to be executed, and can be saved for later + // execution if desired. + + // Invoke the closure. + result = ((unsigned char(*)(float, unsigned int))closure)(42, 5.1); + + // Free the memory associated with the closure. + if (munmap(closure, sizeof(closure)) == -1) + { + // Check errno and handle the error. + } + + return 0; +} + +// Invoking the closure transfers control to this function. +static void +foo_closure(ffi_cif* cif, void* result, void** args, void* userdata) +{ + // Access the arguments to be sent to foo(). + float arg1 = *(float*)args[0]; + unsigned int arg2 = *(unsigned int*)args[1]; + + // Call foo() and save its return value. + unsigned char ret_val = foo(arg1, arg2); + + // Copy the returned value into result. Because the return value of foo() + // is smaller than sizeof(long), typecast it to ffi_arg. Use ffi_sarg + // instead for signed types. + *(ffi_arg*)result = (ffi_arg)ret_val; +} + +// The closed-over function. +unsigned char +foo(unsigned int x, float y) +{ + unsigned char result = x - y; + return result; +} +.Ed +.Sh SEE ALSO +.Xr ffi 3 , +.Xr ffi_prep_cif 3 , +.Xr mmap 2 , +.Xr munmap 2 , +.Xr mprotect 2