cgit.sxemacs.org Git - sxemacs/blob - info/lispref/ffi.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the SXEmacs Lisp Reference Manual.
   3 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
   4 @c Copyright (C) 2005 Zajcev Evgeny <lg@xwem.org>
   5 @c See the file lispref.texi for copying conditions.
   6 @setfilename ../../info/ffi.info
   7
   8 @node Foreign Functions, MULE, Internationalization, Top
   9 @chapter Foreign Function Interface (FFI)
  10 @cindex FO
  11 @cindex FFI
  12 @cindex foreign objects
  13 @cindex foreign functions
  14
  15 @macro FFI
  16 FFI
  17 @end macro
  18
  19   The SXEmacs @dfn{Foreign Function Interface} (@FFI{} for short) adds
  20 support for invoking code written in other programming languages from
  21 within elisp.  The @FFI{} focuses on interaction with C code, but the
  22 basic framework can also be used for interfacing to languages other
  23 than C, provided they support to be compiled to binary and linked into
  24 a @dfn{shared library}.
  25
  26   The SXEmacs @FFI{} can access sharable object files at runtime and
  27 use their definition without relocating or relinking the SXEmacs
  28 binary.  The purpose (and main motivation) therefore clearly is to
  29 supply elisp programmers with a convenient way to implement features
  30 from underlying libraries without even touching the C level.
  31
  32   The @FFI{} feature itself must be considered experimental, though.
  33 It is a lot of effort to secure raw library calls from misuse,
  34 especially because the SXEmacs error handler has no influence on the
  35 events triggered inside of the foreign library.  On the other hand,
  36 keeping foreign function calls under exhaustive surveillance would
  37 noticably slow down the @FFI{}, if not even limit the capabilities at
  38 all.
  39
  40 @menu
  41 * Basic C Types and Functions:: Default type and function bindings
  42                                   from the Standard C library (libc)
  43 * Calling Foreign Functions::   How to call functions defined in an
  44                                   external library.
  45 * Examining and Modifying::     How to examine and modify foreign
  46                                   objects.
  47 * User-Defined Types::          How to reflect custom type definitions
  48                                   in an external library.
  49 * ffi-curl::                    FFI-bindings for the libcurl library.
  50 * ffi-wand::                    FFI-bindings for the libWand library.
  51 @end menu
  52
  53
  54 @node Basic C Types and Functions
  55 @section Basic C Types and Functions
  56
  57   In order to provide a convenient way to access the standard C
  58 library (libc), FFI comes with a set of predefined types and
  59 functions.  Of course, you can access other functions and define other
  60 types beside the ones in libc.  The discussion here is intended to be
  61 a basic introduction to FFI.  To use a specific library see the more
  62 general sections @ref{Calling Foreign Functions} and @ref{User-Defined
  63 Types}.
  64
  65 @menu
  66 * Predefined FFI data types::   A list of predefined, ready-to-go
  67                                   types provided by FFI.
  68 * The pointer form::    A type modifier to reference data.
  69 * The function form::   A type modifier to reference functions.
  70 * The array form::      A type modifier to specify arrays.
  71 * The union form::      A type modifier to specify unions.
  72 * The struct form::     A type modifier to specify stuctures.
  73 * The c-data form::     A type modifier to specify memory blocks.
  74 * FFI type-related functions::  Functions to gather information on types.
  75 @end menu
  76
  77 @node Predefined FFI data types
  78 @subsection Predefined FFI data types
  79
  80   The following assortment lists all predefined C data types.  These
  81 types are also known as Basic FFI types.  We assume these to be well
  82 known and do not explain them further.
  83
  84 @itemize
  85 @item
  86 @code{byte}, @code{unsigned byte}
  87 @item
  88 @code{char}, @code{unsigned-char}
  89 @item
  90 @code{short}, @code{unsigned-short}
  91 @item
  92 @code{int}, @code{unsigned-int}
  93 @item
  94 @code{long}, @code{unsigned-long}
  95 @item
  96 @code{float},
  97 @item
  98 @code{double}
  99 @item
 100 @code{void}
 101 @item
 102 @code{c-string}
 103 @item
 104 @code{c-data}
 105 @end itemize
 106
 107   As with C data types, the actual meaning of these types depends on
 108 the system architecture, but there is no difference between these FFI
 109 predefined types and their C-pendant if FFI is run on the same
 110 machine.
 111
 112   However, the last two types in the list are special in that they are
 113 actually a @code{(pointer char)} (in C known as @samp{char*}), but (as
 114 the name suggests) data of this type form a string on C level, or
 115 arbitrary chunks of (bytewise-oriented) data which is translated to or
 116 translated from an ordinary emacs string.  In constrast, we should
 117 mention that the @samp{char*} is actually solely a pointer to one
 118 character, and @emph{not} a string a priori.
 119
 120   In order to handle arbitrary binary data blocks, the type
 121 @code{c-data} can be used in conjunction with a size parameter (see
 122 The @code{c-data} form).  Strings -- the internal representation
 123 of data of this type -- are (re-)encoded to @code{binary} (i.e. the
 124 generic binary coding system) due to Mule issues.
 125
 126
 127 @node The pointer form
 128 @subsection The @code{pointer} form
 129 @cindex pointer FFI type-modifier
 130
 131   As mentioned in the previous section, every data type can be
 132 pointerised, that is create another FFI-object with the address of the
 133 data (not the data itself).  We say such data @dfn{point to} other
 134 data.
 135
 136   The syntax for this is the form @code{'(pointer @var{data-type})},
 137 so for example the FFI-type @code{'(pointer int)} is the data type
 138 @samp{int*} in C.
 139
 140
 141 @node The function form
 142 @subsection The @code{function} form
 143 @cindex function FFI type-modifier
 144
 145   In addition to pointerised data, there is a special type modifier to