Add man files and info file. Update README. Tag as 2.99.3.
authorgreen <green>
Thu, 14 Feb 2008 22:03:37 +0000 (22:03 +0000)
committergreen <green>
Thu, 14 Feb 2008 22:03:37 +0000 (22:03 +0000)
15 files changed:
libffi/ChangeLog.libffi
libffi/Makefile.am
libffi/Makefile.in
libffi/README
libffi/configure
libffi/configure.ac
libffi/doc/libffi.info [new file with mode: 0644]
libffi/doc/stamp-vti [new file with mode: 0644]
libffi/doc/version.texi
libffi/man/Makefile.am [new file with mode: 0644]
libffi/man/Makefile.in [new file with mode: 0644]
libffi/man/ffi.3 [new file with mode: 0644]
libffi/man/ffi_call.3 [new file with mode: 0644]
libffi/man/ffi_prep_cif.3 [new file with mode: 0644]
libffi/man/ffi_prep_closure.3 [new file with mode: 0644]

index 2a59cfc..c16f2d2 100644 (file)
@@ -1,3 +1,20 @@
+2008-02-14  Anthony Green  <green@redhat.com>
+
+       * 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  <green@redhat.com>
+
+       * 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  <tromey@redhat.com>
 
        * aclocal.m4, Makefile.in, configure, fficonfig.h.in: Rebuilt.
index 9608921..610dabb 100644 (file)
@@ -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 \
index 593e104..1fc2fad 100644 (file)
@@ -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 \
index 56382bb..6eacd9c 100644 (file)
@@ -36,38 +36,21 @@ exist above libffi that handles type conversions for values passed
 between the two languages.
 
 
-Supported Platforms and Prerequisites
-=====================================
-
-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).
-
+Supported Platforms
+===================
+
+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 <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;
-    }
-
-
-
-       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 <green@cygnus.com>.
+libffi was originally written by Anthony Green <green@redhat.com>.
+
+The developers of the GNU Compiler Collection project have made
+innumerable valuable contributions.  See the ChangeLog file for
+details.
 
-Portions of libffi were derived from Gianni Mariani's free gencall
-library for Silicon Graphics machines.
+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 <http://www.vdi.com>. Further enhancements were
-made by Gordon Irlam at Cygnus Solutions <http://www.cygnus.com>.
-
-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.
+Major processor architecture ports were contributed by the following
+developers:
+
+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.
index 8e01b26..9533dc1 100755 (executable)
@@ -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 <http://gcc.gnu.org/bugs.html>.
 #
@@ -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 <bug-autoconf@gnu.org>."
 _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
index 66e6c18..14d3a3c 100644 (file)
@@ -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 (file)
index 0000000..dc7f02c
--- /dev/null
@@ -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
+
+\1f
+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.
+
+\1f
+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.  
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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;
+     }
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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() */
+         }
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: libffi.info,  Node: Index,  Prev: Missing Features,  Up: Top
+
+Index
+*****
+
+\0\b[index\0\b]
+* 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)
+
+
+\1f
+Tag Table:
+Node: Top\7f688
+Node: Introduction\7f1424
+Node: Using libffi\7f3060
+Node: The Basics\7f3495
+Node: Simple Example\7f6102
+Node: Types\7f7129
+Node: Primitive Types\7f7412
+Node: Structures\7f9232
+Node: Type Example\7f10092
+Node: Multiple ABIs\7f11315
+Node: The Closure API\7f11686
+Node: Missing Features\7f14606
+Node: Index\7f15099
+\1f
+End Tag Table
diff --git a/libffi/doc/stamp-vti b/libffi/doc/stamp-vti
new file mode 100644 (file)
index 0000000..b45fbb1
--- /dev/null
@@ -0,0 +1,4 @@
+@set UPDATED 14 February 2008
+@set UPDATED-MONTH February 2008
+@set EDITION 2.99.3
+@set VERSION 2.99.3
index 3ce13b5..b45fbb1 100644 (file)
@@ -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 (file)
index 0000000..cd9e984
--- /dev/null
@@ -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 (file)
index 0000000..66a6fa8
--- /dev/null
@@ -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 (file)
index 0000000..8235b82
--- /dev/null
@@ -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 (file)
index 0000000..48efe13
--- /dev/null
@@ -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 <ffi/ffi.h>
+#include <stdio.h>
+
+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 <ffi/ffi.h>.
+    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 (file)
index 0000000..87e7792
--- /dev/null
@@ -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 <ffitarget.h>
+.
+.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 (file)
index 0000000..186a8d7
--- /dev/null
@@ -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 <ffi/ppc-ffitarget.h>
+and
+.Nm <ffi/x86-ffitarget.h> .
+.Sh EXAMPLES
+.Bd -literal
+#include <ffi/ffi.h>
+#include <sys/mman.h>   // 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 <ffi/ffi.h>.
+    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