geminfo 0.1.0 → 0.1.1

data/path/gems/ffi-1.9.10-x86-mingw32/ext/ffi_c/libffi/doc/libffi.texi

@@ -1,600 +0,0 @@
-\input texinfo   @c -*-texinfo-*-
-@c %**start of header
-@setfilename libffi.info
-@settitle libffi
-@setchapternewpage off
-@c %**end of header
-
-@c Merge the standard indexes into a single one.
-@syncodeindex fn cp
-@syncodeindex vr cp
-@syncodeindex ky cp
-@syncodeindex pg cp
-@syncodeindex tp cp
-
-@include version.texi
-
-@copying
-
-This manual is for Libffi, a portable foreign-function interface
-library.
-
-Copyright @copyright{} 2008, 2010 Red Hat, Inc.
-
-@quotation
-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''.
-
-@end quotation
-@end copying
-
-@dircategory Development
-@direntry
-* libffi: (libffi).             Portable foreign-function interface library.
-@end direntry
-
-@titlepage
-@title Libffi
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-
-@ifnottex
-@node Top
-@top libffi
-
-@insertcopying
-
-@menu
-* Introduction::                What is libffi?
-* Using libffi::                How to use libffi.
-* Missing Features::            Things libffi can't do.
-* Index::                       Index.
-@end menu
-
-@end ifnottex
-
-
-@node Introduction
-@chapter 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 @dfn{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 @dfn{ABI} or @dfn{Application Binary Interface}.
-@cindex calling convention
-@cindex ABI
-@cindex 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.  @samp{Libffi} can be used in such programs to
-provide a bridge from the interpreter program to compiled code.
-
-The @samp{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.
-
-@acronym{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 @samp{libffi} library really only provides the lowest, machine
-dependent layer of a fully featured foreign function interface.  A
-layer must exist above @samp{libffi} that handles type conversions for
-values passed between the two languages.
-@cindex FFI
-@cindex Foreign Function Interface
-
-
-@node Using libffi
-@chapter Using libffi
-
-@menu
-* The Basics::                  The basic libffi API.
-* Simple Example::              A simple example.
-* Types::                       libffi type descriptions.
-* Multiple ABIs::               Different passing styles on one platform.
-* The Closure API::             Writing a generic function.
-* Closure Example::             A closure example.
-@end menu
-
-
-@node The Basics
-@section The Basics
-
-@samp{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 @code{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 @code{ffi_cif}.  The @dfn{cif} in @code{ffi_cif} stands for
-Call InterFace.  To prepare a call interface object, use the function
-@code{ffi_prep_cif}.
-@cindex cif
-
-@findex ffi_prep_cif
-@defun ffi_status ffi_prep_cif (ffi_cif *@var{cif}, ffi_abi @var{abi}, unsigned int @var{nargs}, ffi_type *@var{rtype}, ffi_type **@var{argtypes})
-This initializes @var{cif} according to the given parameters.
-
-@var{abi} is the ABI to use; normally @code{FFI_DEFAULT_ABI} is what
-you want.  @ref{Multiple ABIs} for more information.
-
-@var{nargs} is the number of arguments that this function accepts.
-@samp{libffi} does not yet handle varargs functions; see @ref{Missing
-Features} for more information.
-
-@var{rtype} is a pointer to an @code{ffi_type} structure that
-describes the return type of the function.  @xref{Types}.
-
-@var{argtypes} is a vector of @code{ffi_type} pointers.
-@var{argtypes} must have @var{nargs} elements.  If @var{nargs} is 0,
-this argument is ignored.
-
-@code{ffi_prep_cif} returns a @code{libffi} status code, of type
-@code{ffi_status}.  This will be either @code{FFI_OK} if everything
-worked properly; @code{FFI_BAD_TYPEDEF} if one of the @code{ffi_type}
-objects is incorrect; or @code{FFI_BAD_ABI} if the @var{abi} parameter
-is invalid.
-@end defun
-
-
-To call a function using an initialized @code{ffi_cif}, use the
-@code{ffi_call} function:
-
-@findex ffi_call
-@defun void ffi_call (ffi_cif *@var{cif}, void *@var{fn}, void *@var{rvalue}, void **@var{avalues})
-This calls the function @var{fn} according to the description given in
-@var{cif}.  @var{cif} must have already been prepared using
-@code{ffi_prep_cif}.
-
-@var{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 @var{cif} declares that the function returns
-@code{void} (using @code{ffi_type_void}), then @var{rvalue} is
-ignored.  If @var{rvalue} is @samp{NULL}, then the return value is
-discarded.
-
-@var{avalues} is a vector of @code{void *} pointers that point to the
-memory locations holding the argument values for a call.  If @var{cif}
-declares that the function has no arguments (i.e., @var{nargs} was 0),
-then @var{avalues} is ignored.  Note that argument values may be
-modified by the callee (for instance, structs passed by value); the
-burden of copying pass-by-value arguments is placed on the caller.
-@end defun
-
-
-@node Simple Example
-@section Simple Example
-
-Here is a trivial example that calls @code{puts} a few times.
-
-@example
-#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;
-@}
-@end example
-
-
-@node Types
-@section Types
-
-@menu
-* Primitive Types::             Built-in types.
-* Structures::                  Structure types.
-* Type Example::                Structure type example.
-@end menu
-
-@node Primitive Types
-@subsection Primitive Types
-
-@code{Libffi} provides a number of built-in type descriptors that can
-be used to describe argument and return types:
-
-@table @code
-@item ffi_type_void
-@tindex ffi_type_void
-The type @code{void}.  This cannot be used for argument types, only
-for return values.
-
-@item ffi_type_uint8
-@tindex ffi_type_uint8
-An unsigned, 8-bit integer type.
-
-@item ffi_type_sint8
-@tindex ffi_type_sint8
-A signed, 8-bit integer type.
-
-@item ffi_type_uint16
-@tindex ffi_type_uint16
-An unsigned, 16-bit integer type.
-
-@item ffi_type_sint16
-@tindex ffi_type_sint16
-A signed, 16-bit integer type.
-
-@item ffi_type_uint32
-@tindex ffi_type_uint32
-An unsigned, 32-bit integer type.
-
-@item ffi_type_sint32
-@tindex ffi_type_sint32
-A signed, 32-bit integer type.
-
-@item ffi_type_uint64
-@tindex ffi_type_uint64
-An unsigned, 64-bit integer type.
-
-@item ffi_type_sint64
-@tindex ffi_type_sint64
-A signed, 64-bit integer type.
-
-@item ffi_type_float
-@tindex ffi_type_float
-The C @code{float} type.
-
-@item ffi_type_double
-@tindex ffi_type_double
-The C @code{double} type.
-
-@item ffi_type_uchar
-@tindex ffi_type_uchar
-The C @code{unsigned char} type.
-
-@item ffi_type_schar
-@tindex ffi_type_schar
-The C @code{signed char} type.  (Note that there is not an exact
-equivalent to the C @code{char} type in @code{libffi}; ordinarily you
-should either use @code{ffi_type_schar} or @code{ffi_type_uchar}
-depending on whether @code{char} is signed.)
-
-@item ffi_type_ushort
-@tindex ffi_type_ushort
-The C @code{unsigned short} type.
-
-@item ffi_type_sshort
-@tindex ffi_type_sshort
-The C @code{short} type.
-
-@item ffi_type_uint
-@tindex ffi_type_uint
-The C @code{unsigned int} type.
-
-@item ffi_type_sint
-@tindex ffi_type_sint
-The C @code{int} type.
-
-@item ffi_type_ulong
-@tindex ffi_type_ulong
-The C @code{unsigned long} type.
-
-@item ffi_type_slong
-@tindex ffi_type_slong
-The C @code{long} type.
-
-@item ffi_type_longdouble
-@tindex ffi_type_longdouble
-On platforms that have a C @code{long double} type, this is defined.
-On other platforms, it is not.
-
-@item ffi_type_pointer
-@tindex ffi_type_pointer
-A generic @code{void *} pointer.  You should use this for all
-pointers, regardless of their real type.
-@end table
-
-Each of these is of type @code{ffi_type}, so you must take the address
-when passing to @code{ffi_prep_cif}.
-
-
-@node Structures
-@subsection Structures
-
-Although @samp{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 @samp{libffi} by creating a
-new @code{ffi_type} object for it.
-
-@tindex ffi_type
-@deftp ffi_type
-The @code{ffi_type} has the following members:
-@table @code
-@item size_t size
-This is set by @code{libffi}; you should initialize it to zero.
-
-@item unsigned short alignment
-This is set by @code{libffi}; you should initialize it to zero.
-
-@item unsigned short type
-For a structure, this should be set to @code{FFI_TYPE_STRUCT}.
-
-@item ffi_type **elements
-This is a @samp{NULL}-terminated array of pointers to @code{ffi_type}
-objects.  There is one element per field of the struct.
-@end table
-@end deftp
-
-
-@node Type Example
-@subsection Type Example
-
-The following example initializes a @code{ffi_type} object
-representing the @code{tm} struct from Linux's @file{time.h}.
-
-Here is how the struct is defined:
-
-@example
-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__;
-@};
-@end example
-
-Here is the corresponding code to describe this struct to
-@code{libffi}:
-
-@example
-    @{
-      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() */
-    @}
-@end example
-
-
-@node Multiple ABIs
-@section Multiple ABIs
-
-A given platform may provide multiple different ABIs at once.  For
-instance, the x86 platform has both @samp{stdcall} and @samp{fastcall}
-functions.
-
-@code{libffi} provides some support for this.  However, this is
-necessarily platform-specific.
-
-@c FIXME: document the platforms
-
-@node The Closure API
-@section The Closure API
-
-@code{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 @dfn{closure API}.  Closures are not
-supported on all platforms; you can check the @code{FFI_CLOSURES}
-define to determine whether they are supported on the current
-platform.
-@cindex closures
-@cindex closure API
-@findex FFI_CLOSURES
-
-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:
-
-@findex ffi_closure_alloc
-@defun void *ffi_closure_alloc (size_t @var{size}, void **@var{code})
-Allocate a chunk of memory holding @var{size} bytes.  This returns a
-pointer to the writable address, and sets *@var{code} to the
-corresponding executable address.
-
-@var{size} should be sufficient to hold a @code{ffi_closure} object.
-@end defun
-
-@findex ffi_closure_free
-@defun void ffi_closure_free (void *@var{writable})
-Free memory allocated using @code{ffi_closure_alloc}.  The argument is
-the writable address that was returned.
-@end defun
-
-
-Once you have allocated the memory for a closure, you must construct a
-@code{ffi_cif} describing the function call.  Finally you can prepare
-the closure function:
-
-@findex ffi_prep_closure_loc
-@defun ffi_status ffi_prep_closure_loc (ffi_closure *@var{closure}, ffi_cif *@var{cif}, void (*@var{fun}) (ffi_cif *@var{cif}, void *@var{ret}, void **@var{args}, void *@var{user_data}), void *@var{user_data}, void *@var{codeloc})
-Prepare a closure function.
-
-@var{closure} is the address of a @code{ffi_closure} object; this is
-the writable address returned by @code{ffi_closure_alloc}.
-
-@var{cif} is the @code{ffi_cif} describing the function parameters.
-
-@var{user_data} is an arbitrary datum that is passed, uninterpreted,
-to your closure function.
-
-@var{codeloc} is the executable address returned by
-@code{ffi_closure_alloc}.
-
-@var{fun} is the function which will be called when the closure is
-invoked.  It is called with the arguments:
-@table @var
-@item cif
-The @code{ffi_cif} passed to @code{ffi_prep_closure_loc}.
-
-@item ret
-A pointer to the memory used for the function's return value.
-@var{fun} must fill this, unless the function is declared as returning
-@code{void}.
-@c FIXME: is this NULL for void-returning functions?
-
-@item args
-A vector of pointers to memory holding the arguments to the function.
-
-@item user_data
-The same @var{user_data} that was passed to
-@code{ffi_prep_closure_loc}.
-@end table
-
-@code{ffi_prep_closure_loc} will return @code{FFI_OK} if everything
-went ok, and something else on error.
-@c FIXME: what?
-
-After calling @code{ffi_prep_closure_loc}, you can cast @var{codeloc}
-to the appropriate pointer-to-function type.
-@end defun
-
-You may see old code referring to @code{ffi_prep_closure}.  This
-function is deprecated, as it cannot handle the need for separate
-writable and executable addresses.
-
-@node Closure Example
-@section Closure Example
-
-A trivial example that creates a new @code{puts} by binding 
-@code{fputs} with @code{stdin}.
-
-@example
-#include <stdio.h>
-#include <ffi.h>
-
-/* Acts like puts with the file given at time of enclosure. */
-void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[], 
-                  FILE *stream)
-@{
-  *ret = fputs(*(char **)args[0], stream);
-@}
-
-int main()
-@{
-  ffi_cif cif;
-  ffi_type *args[1];
-  ffi_closure *closure;
-
-  int (*bound_puts)(char *);
-  int rc;
-  
-  /* Allocate closure and bound_puts */
-  closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts);
-
-  if (closure)
-    @{
-      /* Initialize the argument info vectors */
-      args[0] = &ffi_type_pointer;
-
-      /* Initialize the cif */
-      if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
-                       &ffi_type_uint, args) == FFI_OK)
-        @{
-          /* Initialize the closure, setting stream to stdout */
-          if (ffi_prep_closure_loc(closure, &cif, puts_binding, 
-                                   stdout, bound_puts) == FFI_OK)
-            @{
-              rc = bound_puts("Hello World!");
-              /* rc now holds the result of the call to fputs */
-            @}
-        @}
-    @}
-
-  /* Deallocate both closure, and bound_puts */
-  ffi_closure_free(closure);
-
-  return 0;
-@}
-
-@end example
-
-
-@node Missing Features
-@chapter Missing Features
-
-@code{libffi} is missing a few features.  We welcome patches to add
-support for these.
-
-@itemize @bullet
-@item
-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.
-
-@item
-There is no support for bit fields in structures.
-
-@item
-The closure API is
-
-@c FIXME: ...
-
-@item
-The ``raw'' API is undocumented.
-@c argument promotion?
-@c unions?
-@c anything else?
-@end itemize
-
-
-@node Index
-@unnumbered Index
-
-@printindex cp
-
-@bye