doc/libffi.info

   1 This is ../libffi/doc/libffi.info, produced by makeinfo version 4.11
   2 from ../libffi/doc/libffi.texi.
   3
   4 This manual is for Libffi, a portable foreign-function interface
   5 library.
   6
   7    Copyright (C) 2008 Red Hat, Inc.
   8
   9      Permission is granted to copy, distribute and/or modify this
  10      document under the terms of the GNU General Public License as
  11      published by the Free Software Foundation; either version 2, or
  12      (at your option) any later version.  A copy of the license is
  13      included in the section entitled "GNU General Public License".
  14
  15
  16 INFO-DIR-SECTION
  17 START-INFO-DIR-ENTRY
  18 * libffi: (libffi).             Portable foreign-function interface library.
  19 END-INFO-DIR-ENTRY
  20
  21 \1f
  22 File: libffi.info,  Node: Top,  Next: Introduction,  Up: (dir)
  23
  24 libffi
  25 ******
  26
  27 This manual is for Libffi, a portable foreign-function interface
  28 library.
  29
  30    Copyright (C) 2008 Red Hat, Inc.
  31
  32      Permission is granted to copy, distribute and/or modify this
  33      document under the terms of the GNU General Public License as
  34      published by the Free Software Foundation; either version 2, or
  35      (at your option) any later version.  A copy of the license is
  36      included in the section entitled "GNU General Public License".
  37
  38
  39 * Menu:
  40
  41 * Introduction::                What is libffi?
  42 * Using libffi::                How to use libffi.
  43 * Missing Features::            Things libffi can't do.
  44 * Index::                       Index.
  45
  46 \1f
  47 File: libffi.info,  Node: Introduction,  Next: Using libffi,  Prev: Top,  Up: Top
  48
  49 1 What is libffi?
  50 *****************
  51
  52 Compilers for high level languages generate code that follow certain
  53 conventions.  These conventions are necessary, in part, for separate
  54 compilation to work.  One such convention is the "calling convention".
  55 The calling convention is a set of assumptions made by the compiler
  56 about where function arguments will be found on entry to a function.  A
  57 calling convention also specifies where the return value for a function
  58 is found.  The calling convention is also sometimes called the "ABI" or
  59 "Application Binary Interface".
  60
  61    Some programs may not know at the time of compilation what arguments
  62 are to be passed to a function.  For instance, an interpreter may be
  63 told at run-time about the number and types of arguments used to call a
  64 given function.  `Libffi' can be used in such programs to provide a
  65 bridge from the interpreter program to compiled code.
  66
  67    The `libffi' library provides a portable, high level programming
  68 interface to various calling conventions.  This allows a programmer to
  69 call any function specified by a call interface description at run time.
  70
  71    FFI stands for Foreign Function Interface.  A foreign function
  72 interface is the popular name for the interface that allows code
  73 written in one language to call code written in another language.  The
  74 `libffi' library really only provides the lowest, machine dependent
  75 layer of a fully featured foreign function interface.  A layer must
  76 exist above `libffi' that handles type conversions for values passed
  77 between the two languages.
  78
  79 \1f
  80 File: libffi.info,  Node: Using libffi,  Next: Missing Features,  Prev: Introduction,  Up: Top
  81
  82 2 Using libffi
  83 **************
  84
  85 * Menu:
  86
  87 * The Basics::                  The basic libffi API.
  88 * Simple Example::              A simple example.
  89 * Types::                       libffi type descriptions.
  90 * Multiple ABIs::               Different passing styles on one platform.
  91 * The Closure API::             Writing a generic function.
  92
  93 \1f
  94 File: libffi.info,  Node: The Basics,  Next: Simple Example,  Up: Using libffi
  95
  96 2.1 The Basics
  97 ==============
  98
  99 `Libffi' assumes that you have a pointer to the function you wish to
 100 call and that you know the number and types of arguments to pass it, as
 101 well as the return type of the function.
 102
 103    The first thing you must do is create an `ffi_cif' object that
 104 matches the signature of the function you wish to call.  This is a
 105 separate step because it is common to make multiple calls using a
 106 single `ffi_cif'.  The "cif" in `ffi_cif' stands for Call InterFace.
 107 To prepare a call interface object, use the function `ffi_prep_cif'.
 108
 109  -- Function: ffi_status ffi_prep_cif (ffi_cif *CIF, ffi_abi ABI,
 110           unsigned int NARGS, ffi_type *RTYPE, ffi_type **ARGTYPES)
 111      This initializes CIF according to the given parameters.
 112
 113      ABI is the ABI to use; normally `FFI_DEFAULT_ABI' is what you
 114      want.  *note Multiple ABIs:: for more information.
 115
 116      NARGS is the number of arguments that this function accepts.
 117      `libffi' does not yet handle varargs functions; see *note Missing
 118      Features:: for more information.
 119
 120      RTYPE is a pointer to an `ffi_type' structure that describes the
 121      return type of the function.  *Note Types::.
 122
 123      ARGTYPES is a vector of `ffi_type' pointers.  ARGTYPES must have
 124      NARGS elements.  If NARGS is 0, this argument is ignored.
 125
 126      `ffi_prep_cif' returns a `libffi' status code, of type
 127      `ffi_status'.  This will be either `FFI_OK' if everything worked
 128      properly; `FFI_BAD_TYPEDEF' if one of the `ffi_type' objects is
 129      incorrect; or `FFI_BAD_ABI' if the ABI parameter is invalid.
 130
 131    To call a function using an initialized `ffi_cif', use the
 132 `ffi_call' function:
 133
 134  -- Function: void ffi_call (ffi_cif *CIF, void *FN, void *RVALUE, void
 135           **AVALUES)
 136      This calls the function FN according to the description given in
 137      CIF.  CIF must have already been prepared using `ffi_prep_cif'.
 138
 139      RVALUE is a pointer to a chunk of memory that will hold the result
 140      of the function call.  This must be large enough to hold the
 141      result and must be suitably aligned; it is the caller's
 142      responsibility to ensure this.  If CIF declares that the function
 143      returns `void' (using `ffi_type_void'), then RVALUE is ignored.
 144      If RVALUE is `NULL', then the return value is discarded.
 145
 146      AVALUES is a vector of `void *' pointers that point to the memory
 147      locations holding the argument values for a call.  If CIF declares
 148      that the function has no arguments (i.e., NARGS was 0), then
 149      AVALUES is ignored.
 150
 151 \1f
 152 File: libffi.info,  Node: Simple Example,  Next: Types,  Prev: The Basics,  Up: Using libffi
 153
 154 2.2 Simple Example
 155 ==================
 156
 157 Here is a trivial example that calls `puts' a few times.
 158
 159      #include <stdio.h>
 160      #include <ffi.h>
 161
 162      int main()
 163      {
 164        ffi_cif cif;
 165        ffi_type *args[1];
 166        void *values[1];
 167        char *s;
 168        int rc;
 169
 170        /* Initialize the argument info vectors */
 171        args[0] = &ffi_type_pointer;
 172        values[0] = &s;
 173
 174        /* Initialize the cif */
 175        if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
 176                        &ffi_type_uint, args) == FFI_OK)
 177          {
 178            s = "Hello World!";
 179            ffi_call(&cif, puts, &rc, values);
 180            /* rc now holds the result of the call to puts */
 181
 182            /* values holds a pointer to the function's arg, so to
 183               call puts() again all we need to do is change the
 184               value of s */
 185            s = "This is cool!";
 186            ffi_call(&cif, puts, &rc, values);
 187          }
 188
 189        return 0;
 190      }
 191
 192 \1f
 193 File: libffi.info,  Node: Types,  Next: Multiple ABIs,  Prev: Simple Example,  Up: Using libffi
 194
 195 2.3 Types
 196 =========
 197
 198 * Menu:
 199
 200 * Primitive Types::             Built-in types.
 201 * Structures::                  Structure types.
 202 * Type Example::                Structure type example.
 203
 204 \1f
 205 File: libffi.info,  Node: Primitive Types,  Next: Structures,  Up: Types
 206
 207 2.3.1 Primitive Types
 208 ---------------------
 209
 210 `Libffi' provides a number of built-in type descriptors that can be
 211 used to describe argument and return types:
 212
 213 `ffi_type_void'
 214      The type `void'.  This cannot be used for argument types, only for
 215      return values.
 216
 217 `ffi_type_uint8'
 218      An unsigned, 8-bit integer type.
 219
 220 `ffi_type_sint8'
 221      A signed, 8-bit integer type.
 222
 223 `ffi_type_uint16'
 224      An unsigned, 16-bit integer type.
 225
 226 `ffi_type_sint16'
 227      A signed, 16-bit integer type.
 228
 229 `ffi_type_uint32'
 230      An unsigned, 32-bit integer type.
 231
 232 `ffi_type_sint32'
 233      A signed, 32-bit integer type.
 234
 235 `ffi_type_uint64'
 236      An unsigned, 64-bit integer type.
 237
 238 `ffi_type_sint64'
 239      A signed, 64-bit integer type.
 240
 241 `ffi_type_float'
 242      The C `float' type.
 243
 244 `ffi_type_double'
 245      The C `double' type.
 246
 247 `ffi_type_uchar'
 248      The C `unsigned char' type.
 249
 250 `ffi_type_schar'
 251      The C `signed char' type.  (Note that there is not an exact
 252      equivalent to the C `char' type in `libffi'; ordinarily you should
 253      either use `ffi_type_schar' or `ffi_type_uchar' depending on
 254      whether `char' is signed.)
 255
 256 `ffi_type_ushort'
 257      The C `unsigned short' type.
 258
 259 `ffi_type_sshort'
 260      The C `short' type.
 261
 262 `ffi_type_uint'
 263      The C `unsigned int' type.
 264
 265 `ffi_type_sint'
 266      The C `int' type.
 267
 268 `ffi_type_ulong'
 269      The C `unsigned long' type.
 270
 271 `ffi_type_slong'
 272      The C `long' type.
 273
 274 `ffi_type_longdouble'
 275      On platforms that have a C `long double' type, this is defined.
 276      On other platforms, it is not.
 277
 278 `ffi_type_pointer'
 279      A generic `void *' pointer.  You should use this for all pointers,
 280      regardless of their real type.
 281
 282    Each of these is of type `ffi_type', so you must take the address
 283 when passing to `ffi_prep_cif'.
 284
 285 \1f
 286 File: libffi.info,  Node: Structures,  Next: Type Example,  Prev: Primitive Types,  Up: Types
 287
 288 2.3.2 Structures
 289 ----------------
 290
 291 Although `libffi' has no special support for unions or bit-fields, it
 292 is perfectly happy passing structures back and forth.  You must first
 293 describe the structure to `libffi' by creating a new `ffi_type' object
 294 for it.
 295
 296  -- ffi_type:
 297      The `ffi_type' has the following members:
 298     `size_t size'
 299           This is set by `libffi'; you should initialize it to zero.
 300
 301     `unsigned short alignment'
 302           This is set by `libffi'; you should initialize it to zero.
 303
 304     `unsigned short type'
 305           For a structure, this should be set to `FFI_TYPE_STRUCT'.
 306
 307     `ffi_type **elements'
 308           This is a `NULL'-terminated array of pointers to `ffi_type'
 309           objects.  There is one element per field of the struct.
 310
 311 \1f
 312 File: libffi.info,  Node: Type Example,  Prev: Structures,  Up: Types
 313
 314 2.3.3 Type Example
 315 ------------------
 316
 317 The following example initializes a `ffi_type' object representing the
 318 `tm' struct from Linux's `time.h'.
 319
 320    Here is how the struct is defined:
 321
 322      struct tm {
 323          int tm_sec;
 324          int tm_min;
 325          int tm_hour;
 326          int tm_mday;
 327          int tm_mon;
 328          int tm_year;
 329          int tm_wday;
 330          int tm_yday;
 331          int tm_isdst;
 332          /* Those are for future use. */
 333          long int __tm_gmtoff__;
 334          __const char *__tm_zone__;
 335      };
 336
 337    Here is the corresponding code to describe this struct to `libffi':
 338
 339          {
 340            ffi_type tm_type;
 341            ffi_type *tm_type_elements[12];
 342            int i;
 343
 344            tm_type.size = tm_type.alignment = 0;
 345            tm_type.elements = &tm_type_elements;
 346
 347            for (i = 0; i < 9; i++)
 348                tm_type_elements[i] = &ffi_type_sint;
 349
 350            tm_type_elements[9] = &ffi_type_slong;
 351            tm_type_elements[10] = &ffi_type_pointer;
 352            tm_type_elements[11] = NULL;
 353
 354            /* tm_type can now be used to represent tm argument types and
 355          return types for ffi_prep_cif() */
 356          }
 357
 358 \1f
 359 File: libffi.info,  Node: Multiple ABIs,  Next: The Closure API,  Prev: Types,  Up: Using libffi
 360
 361 2.4 Multiple ABIs
 362 =================
 363
 364 A given platform may provide multiple different ABIs at once.  For
 365 instance, the x86 platform has both `stdcall' and `fastcall' functions.
 366
 367    `libffi' provides some support for this.  However, this is
 368 necessarily platform-specific.
 369
 370 \1f
 371 File: libffi.info,  Node: The Closure API,  Prev: Multiple ABIs,  Up: Using libffi
 372
 373 2.5 The Closure API
 374 ===================
 375
 376 `libffi' also provides a way to write a generic function - a function
 377 that can accept and decode any combination of arguments.  This can be
 378 useful when writing an interpreter, or to provide wrappers for
 379 arbitrary functions.
 380
 381    This facility is called the "closure API".  Closures are not
 382 supported on all platforms; you can check the `FFI_CLOSURES' define to
 383 determine whether they are supported on the current platform.
 384
 385    Because closures work by assembling a tiny function at runtime, they
 386 require special allocation on platforms that have a non-executable
 387 heap.  Memory management for closures is handled by a pair of functions:
 388
 389  -- Function: void *ffi_closure_alloc (size_t SIZE, void **CODE)
 390      Allocate a chunk of memory holding SIZE bytes.  This returns a
 391      pointer to the writable address, and sets *CODE to the
 392      corresponding executable address.
 393
 394      SIZE should be sufficient to hold a `ffi_closure' object.
 395
 396  -- Function: void ffi_closure_free (void *WRITABLE)
 397      Free memory allocated using `ffi_closure_alloc'.  The argument is
 398      the writable address that was returned.
 399
 400    Once you have allocated the memory for a closure, you must construct
 401 a `ffi_cif' describing the function call.  Finally you can prepare the
 402 closure function:
 403
 404  -- Function: ffi_status ffi_prep_closure_loc (ffi_closure *CLOSURE,
 405           ffi_cif *CIF, void (*FUN) (ffi_cif *CIF, void *RET, void
 406           **ARGS, void *USER_DATA), void *USER_DATA, void *CODELOC)
 407      Prepare a closure function.
 408
 409      CLOSURE is the address of a `ffi_closure' object; this is the
 410      writable address returned by `ffi_closure_alloc'.
 411
 412      CIF is the `ffi_cif' describing the function parameters.
 413
 414      USER_DATA is an arbitrary datum that is passed, uninterpreted, to
 415      your closure function.
 416
 417      CODELOC is the executable address returned by `ffi_closure_alloc'.
 418
 419      FUN is the function which will be called when the closure is
 420      invoked.  It is called with the arguments:
 421     CIF
 422           The `ffi_cif' passed to `ffi_prep_closure_loc'.
 423
 424     RET
 425           A pointer to the memory used for the function's return value.
 426           FUN must fill this, unless the function is declared as
 427           returning `void'.
 428
 429     ARGS
 430           A vector of pointers to memory holding the arguments to the
 431           function.
 432
 433     USER_DATA
 434           The same USER_DATA that was passed to `ffi_prep_closure_loc'.
 435
 436      `ffi_prep_closure_loc' will return `FFI_OK' if everything went ok,
 437      and something else on error.
 438
 439      After calling `ffi_prep_closure_loc', you can cast CODELOC to the
 440      appropriate pointer-to-function type.
 441
 442    You may see old code referring to `ffi_prep_closure'.  This function
 443 is deprecated, as it cannot handle the need for separate writable and
 444 executable addresses.
 445
 446 \1f
 447 File: libffi.info,  Node: Missing Features,  Next: Index,  Prev: Using libffi,  Up: Top
 448
 449 3 Missing Features
 450 ******************
 451
 452 `libffi' is missing a few features.  We welcome patches to add support
 453 for these.
 454
 455    * There is no support for calling varargs functions.  This may work
 456      on some platforms, depending on how the ABI is defined, but it is
 457      not reliable.
 458
 459    * There is no support for bit fields in structures.
 460
 461    * The closure API is
 462
 463    * The "raw" API is undocumented.
 464
 465 \1f
 466 File: libffi.info,  Node: Index,  Prev: Missing Features,  Up: Top
 467
 468 Index
 469 *****
 470
 471 \0\b[index\0\b]
 472 * Menu:
 473
 474 * :                                      Structures.           (line 12)
 475 * ABI:                                   Introduction.         (line 13)
 476 * Application Binary Interface:          Introduction.         (line 13)
 477 * calling convention:                    Introduction.         (line 13)
 478 * cif:                                   The Basics.           (line 14)
 479 * closure API:                           The Closure API.      (line 13)
 480 * closures:                              The Closure API.      (line 13)
 481 * FFI:                                   Introduction.         (line 31)
 482 * ffi_call:                              The Basics.           (line 41)
 483 * ffi_closure_alloca:                    The Closure API.      (line 19)
 484 * ffi_closure_free:                      The Closure API.      (line 26)
 485 * FFI_CLOSURES:                          The Closure API.      (line 13)
 486 * ffi_prep_cif:                          The Basics.           (line 16)
 487 * ffi_prep_closure_loc:                  The Closure API.      (line 34)
 488 * ffi_status <1>:                        The Closure API.      (line 37)
 489 * ffi_status:                            The Basics.           (line 18)
 490 * ffi_type:                              Structures.           (line 11)
 491 * ffi_type_double:                       Primitive Types.      (line 41)
 492 * ffi_type_float:                        Primitive Types.      (line 38)
 493 * ffi_type_longdouble:                   Primitive Types.      (line 71)
 494 * ffi_type_pointer:                      Primitive Types.      (line 75)
 495 * ffi_type_schar:                        Primitive Types.      (line 47)
 496 * ffi_type_sint:                         Primitive Types.      (line 62)
 497 * ffi_type_sint16:                       Primitive Types.      (line 23)
 498 * ffi_type_sint32:                       Primitive Types.      (line 29)
 499 * ffi_type_sint64:                       Primitive Types.      (line 35)
 500 * ffi_type_sint8:                        Primitive Types.      (line 17)
 501 * ffi_type_slong:                        Primitive Types.      (line 68)
 502 * ffi_type_sshort:                       Primitive Types.      (line 56)
 503 * ffi_type_uchar:                        Primitive Types.      (line 44)
 504 * ffi_type_uint:                         Primitive Types.      (line 59)
 505 * ffi_type_uint16:                       Primitive Types.      (line 20)
 506 * ffi_type_uint32:                       Primitive Types.      (line 26)
 507 * ffi_type_uint64:                       Primitive Types.      (line 32)
 508 * ffi_type_uint8:                        Primitive Types.      (line 14)
 509 * ffi_type_ulong:                        Primitive Types.      (line 65)
 510 * ffi_type_ushort:                       Primitive Types.      (line 53)
 511 * ffi_type_void:                         Primitive Types.      (line 10)
 512 * Foreign Function Interface:            Introduction.         (line 31)
 513 * void <1>:                              The Closure API.      (line 20)
 514 * void:                                  The Basics.           (line 43)
 515
 516
 517 \1f
 518 Tag Table:
 519 Node: Top\7f688
 520 Node: Introduction\7f1424
 521 Node: Using libffi\7f3060
 522 Node: The Basics\7f3495
 523 Node: Simple Example\7f6102
 524 Node: Types\7f7129
 525 Node: Primitive Types\7f7412
 526 Node: Structures\7f9232
 527 Node: Type Example\7f10092
 528 Node: Multiple ABIs\7f11315
 529 Node: The Closure API\7f11686
 530 Node: Missing Features\7f14606
 531 Node: Index\7f15099
 532 \1f
 533 End Tag Table