f92aae6e19d73f9e320c562d1449b16700e095de
[libffi.git] / doc / libffi.info
1 This is /home/green/libffi/doc/libffi.info, produced by makeinfo
2 version 4.13 from /home/green/libffi/doc/libffi.texi.
3
4 This manual is for Libffi, a portable foreign-function interface
5 library.
6
7    Copyright (C) 2008, 2010 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 Development
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, 2010 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 * Closure Example::             A closure example.
93
94 \1f
95 File: libffi.info,  Node: The Basics,  Next: Simple Example,  Up: Using libffi
96
97 2.1 The Basics
98 ==============
99
100 `Libffi' assumes that you have a pointer to the function you wish to
101 call and that you know the number and types of arguments to pass it, as
102 well as the return type of the function.
103
104    The first thing you must do is create an `ffi_cif' object that
105 matches the signature of the function you wish to call.  This is a
106 separate step because it is common to make multiple calls using a
107 single `ffi_cif'.  The "cif" in `ffi_cif' stands for Call InterFace.
108 To prepare a call interface object, use the function `ffi_prep_cif'.  
109
110  -- Function: ffi_status ffi_prep_cif (ffi_cif *CIF, ffi_abi ABI,
111           unsigned int NARGS, ffi_type *RTYPE, ffi_type **ARGTYPES)
112      This initializes CIF according to the given parameters.
113
114      ABI is the ABI to use; normally `FFI_DEFAULT_ABI' is what you
115      want.  *note Multiple ABIs:: for more information.
116
117      NARGS is the number of arguments that this function accepts.
118      `libffi' does not yet handle varargs functions; see *note Missing
119      Features:: for more information.
120
121      RTYPE is a pointer to an `ffi_type' structure that describes the
122      return type of the function.  *Note Types::.
123
124      ARGTYPES is a vector of `ffi_type' pointers.  ARGTYPES must have
125      NARGS elements.  If NARGS is 0, this argument is ignored.
126
127      `ffi_prep_cif' returns a `libffi' status code, of type
128      `ffi_status'.  This will be either `FFI_OK' if everything worked
129      properly; `FFI_BAD_TYPEDEF' if one of the `ffi_type' objects is
130      incorrect; or `FFI_BAD_ABI' if the ABI parameter is invalid.
131
132    To call a function using an initialized `ffi_cif', use the
133 `ffi_call' function:
134
135  -- Function: void ffi_call (ffi_cif *CIF, void *FN, void *RVALUE, void
136           **AVALUES)
137      This calls the function FN according to the description given in
138      CIF.  CIF must have already been prepared using `ffi_prep_cif'.
139
140      RVALUE is a pointer to a chunk of memory that will hold the result
141      of the function call.  This must be large enough to hold the
142      result and must be suitably aligned; it is the caller's
143      responsibility to ensure this.  If CIF declares that the function
144      returns `void' (using `ffi_type_void'), then RVALUE is ignored.
145      If RVALUE is `NULL', then the return value is discarded.
146
147      AVALUES is a vector of `void *' pointers that point to the memory
148      locations holding the argument values for a call.  If CIF declares
149      that the function has no arguments (i.e., NARGS was 0), then
150      AVALUES is ignored.
151
152 \1f
153 File: libffi.info,  Node: Simple Example,  Next: Types,  Prev: The Basics,  Up: Using libffi
154
155 2.2 Simple Example
156 ==================
157
158 Here is a trivial example that calls `puts' a few times.
159
160      #include <stdio.h>
161      #include <ffi.h>
162
163      int main()
164      {
165        ffi_cif cif;
166        ffi_type *args[1];
167        void *values[1];
168        char *s;
169        int rc;
170
171        /* Initialize the argument info vectors */
172        args[0] = &ffi_type_pointer;
173        values[0] = &s;
174
175        /* Initialize the cif */
176        if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
177                        &ffi_type_uint, args) == FFI_OK)
178          {
179            s = "Hello World!";
180            ffi_call(&cif, puts, &rc, values);
181            /* rc now holds the result of the call to puts */
182
183            /* values holds a pointer to the function's arg, so to
184               call puts() again all we need to do is change the
185               value of s */
186            s = "This is cool!";
187            ffi_call(&cif, puts, &rc, values);
188          }
189
190        return 0;
191      }
192
193 \1f
194 File: libffi.info,  Node: Types,  Next: Multiple ABIs,  Prev: Simple Example,  Up: Using libffi
195
196 2.3 Types
197 =========
198
199 * Menu:
200
201 * Primitive Types::             Built-in types.
202 * Structures::                  Structure types.
203 * Type Example::                Structure type example.
204
205 \1f
206 File: libffi.info,  Node: Primitive Types,  Next: Structures,  Up: Types
207
208 2.3.1 Primitive Types
209 ---------------------
210
211 `Libffi' provides a number of built-in type descriptors that can be
212 used to describe argument and return types:
213
214 `ffi_type_void'
215      The type `void'.  This cannot be used for argument types, only for
216      return values.
217
218 `ffi_type_uint8'
219      An unsigned, 8-bit integer type.
220
221 `ffi_type_sint8'
222      A signed, 8-bit integer type.
223
224 `ffi_type_uint16'
225      An unsigned, 16-bit integer type.
226
227 `ffi_type_sint16'
228      A signed, 16-bit integer type.
229
230 `ffi_type_uint32'
231      An unsigned, 32-bit integer type.
232
233 `ffi_type_sint32'
234      A signed, 32-bit integer type.
235
236 `ffi_type_uint64'
237      An unsigned, 64-bit integer type.
238
239 `ffi_type_sint64'
240      A signed, 64-bit integer type.
241
242 `ffi_type_float'
243      The C `float' type.
244
245 `ffi_type_double'
246      The C `double' type.
247
248 `ffi_type_uchar'
249      The C `unsigned char' type.
250
251 `ffi_type_schar'
252      The C `signed char' type.  (Note that there is not an exact
253      equivalent to the C `char' type in `libffi'; ordinarily you should
254      either use `ffi_type_schar' or `ffi_type_uchar' depending on
255      whether `char' is signed.)
256
257 `ffi_type_ushort'
258      The C `unsigned short' type.
259
260 `ffi_type_sshort'
261      The C `short' type.
262
263 `ffi_type_uint'
264      The C `unsigned int' type.
265
266 `ffi_type_sint'
267      The C `int' type.
268
269 `ffi_type_ulong'
270      The C `unsigned long' type.
271
272 `ffi_type_slong'
273      The C `long' type.
274
275 `ffi_type_longdouble'
276      On platforms that have a C `long double' type, this is defined.
277      On other platforms, it is not.
278
279 `ffi_type_pointer'
280      A generic `void *' pointer.  You should use this for all pointers,
281      regardless of their real type.
282
283    Each of these is of type `ffi_type', so you must take the address
284 when passing to `ffi_prep_cif'.
285
286 \1f
287 File: libffi.info,  Node: Structures,  Next: Type Example,  Prev: Primitive Types,  Up: Types
288
289 2.3.2 Structures
290 ----------------
291
292 Although `libffi' has no special support for unions or bit-fields, it
293 is perfectly happy passing structures back and forth.  You must first
294 describe the structure to `libffi' by creating a new `ffi_type' object
295 for it.
296
297  -- ffi_type:
298      The `ffi_type' has the following members:
299     `size_t size'
300           This is set by `libffi'; you should initialize it to zero.
301
302     `unsigned short alignment'
303           This is set by `libffi'; you should initialize it to zero.
304
305     `unsigned short type'
306           For a structure, this should be set to `FFI_TYPE_STRUCT'.
307
308     `ffi_type **elements'
309           This is a `NULL'-terminated array of pointers to `ffi_type'
310           objects.  There is one element per field of the struct.
311
312 \1f
313 File: libffi.info,  Node: Type Example,  Prev: Structures,  Up: Types
314
315 2.3.3 Type Example
316 ------------------
317
318 The following example initializes a `ffi_type' object representing the
319 `tm' struct from Linux's `time.h'.
320
321    Here is how the struct is defined:
322
323      struct tm {
324          int tm_sec;
325          int tm_min;
326          int tm_hour;
327          int tm_mday;
328          int tm_mon;
329          int tm_year;
330          int tm_wday;
331          int tm_yday;
332          int tm_isdst;
333          /* Those are for future use. */
334          long int __tm_gmtoff__;
335          __const char *__tm_zone__;
336      };
337
338    Here is the corresponding code to describe this struct to `libffi':
339
340          {
341            ffi_type tm_type;
342            ffi_type *tm_type_elements[12];
343            int i;
344
345            tm_type.size = tm_type.alignment = 0;
346            tm_type.elements = &tm_type_elements;
347
348            for (i = 0; i < 9; i++)
349                tm_type_elements[i] = &ffi_type_sint;
350
351            tm_type_elements[9] = &ffi_type_slong;
352            tm_type_elements[10] = &ffi_type_pointer;
353            tm_type_elements[11] = NULL;
354
355            /* tm_type can now be used to represent tm argument types and
356          return types for ffi_prep_cif() */
357          }
358
359 \1f
360 File: libffi.info,  Node: Multiple ABIs,  Next: The Closure API,  Prev: Types,  Up: Using libffi
361
362 2.4 Multiple ABIs
363 =================
364
365 A given platform may provide multiple different ABIs at once.  For
366 instance, the x86 platform has both `stdcall' and `fastcall' functions.
367
368    `libffi' provides some support for this.  However, this is
369 necessarily platform-specific.
370
371 \1f
372 File: libffi.info,  Node: The Closure API,  Next: Closure Example,  Prev: Multiple ABIs,  Up: Using libffi
373
374 2.5 The Closure API
375 ===================
376
377 `libffi' also provides a way to write a generic function - a function
378 that can accept and decode any combination of arguments.  This can be
379 useful when writing an interpreter, or to provide wrappers for
380 arbitrary functions.
381
382    This facility is called the "closure API".  Closures are not
383 supported on all platforms; you can check the `FFI_CLOSURES' define to
384 determine whether they are supported on the current platform.  
385
386    Because closures work by assembling a tiny function at runtime, they
387 require special allocation on platforms that have a non-executable
388 heap.  Memory management for closures is handled by a pair of functions:
389
390  -- Function: void *ffi_closure_alloc (size_t SIZE, void **CODE)
391      Allocate a chunk of memory holding SIZE bytes.  This returns a
392      pointer to the writable address, and sets *CODE to the
393      corresponding executable address.
394
395      SIZE should be sufficient to hold a `ffi_closure' object.
396
397  -- Function: void ffi_closure_free (void *WRITABLE)
398      Free memory allocated using `ffi_closure_alloc'.  The argument is
399      the writable address that was returned.
400
401    Once you have allocated the memory for a closure, you must construct
402 a `ffi_cif' describing the function call.  Finally you can prepare the
403 closure function:
404
405  -- Function: ffi_status ffi_prep_closure_loc (ffi_closure *CLOSURE,
406           ffi_cif *CIF, void (*FUN) (ffi_cif *CIF, void *RET, void
407           **ARGS, void *USER_DATA), void *USER_DATA, void *CODELOC)
408      Prepare a closure function.
409
410      CLOSURE is the address of a `ffi_closure' object; this is the
411      writable address returned by `ffi_closure_alloc'.
412
413      CIF is the `ffi_cif' describing the function parameters.
414
415      USER_DATA is an arbitrary datum that is passed, uninterpreted, to
416      your closure function.
417
418      CODELOC is the executable address returned by `ffi_closure_alloc'.
419
420      FUN is the function which will be called when the closure is
421      invoked.  It is called with the arguments:
422     CIF
423           The `ffi_cif' passed to `ffi_prep_closure_loc'.
424
425     RET
426           A pointer to the memory used for the function's return value.
427           FUN must fill this, unless the function is declared as
428           returning `void'.
429
430     ARGS
431           A vector of pointers to memory holding the arguments to the
432           function.
433
434     USER_DATA
435           The same USER_DATA that was passed to `ffi_prep_closure_loc'.
436
437      `ffi_prep_closure_loc' will return `FFI_OK' if everything went ok,
438      and something else on error.
439
440      After calling `ffi_prep_closure_loc', you can cast CODELOC to the
441      appropriate pointer-to-function type.
442
443    You may see old code referring to `ffi_prep_closure'.  This function
444 is deprecated, as it cannot handle the need for separate writable and
445 executable addresses.
446
447 \1f
448 File: libffi.info,  Node: Closure Example,  Prev: The Closure API,  Up: Using libffi
449
450 2.6 Closure Example
451 ===================
452
453 A trivial example that creates a new `puts' by binding `fputs' with
454 `stdin'.
455
456      #include <stdio.h>
457      #include <ffi.h>
458
459      /* Acts like puts with the file given at time of enclosure. */
460      void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[],
461                        FILE *stream)
462      {
463        *ret = fputs(*(char **)args[0], stream);
464      }
465
466      int main()
467      {
468        ffi_cif cif;
469        ffi_type *args[1];
470        ffi_closure *closure;
471
472        int (*bound_puts)(char *);
473        int rc;
474
475        /* Allocate closure and bound_puts */
476        closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts);
477
478        if (closure)
479          {
480            /* Initialize the argument info vectors */
481            args[0] = &ffi_type_pointer;
482
483            /* Initialize the cif */
484            if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
485                             &ffi_type_uint, args) == FFI_OK)
486              {
487                /* Initialize the closure, setting stream to stdout */
488                if (ffi_prep_closure_loc(closure, &cif, puts_binding,
489                                         stdout, bound_puts) == FFI_OK)
490                  {
491                    rc = bound_puts("Hello World!");
492                    /* rc now holds the result of the call to fputs */
493                  }
494              }
495          }
496
497        /* Deallocate both closure, and bound_puts */
498        ffi_closure_free(closure);
499
500        return 0;
501      }
502
503 \1f
504 File: libffi.info,  Node: Missing Features,  Next: Index,  Prev: Using libffi,  Up: Top
505
506 3 Missing Features
507 ******************
508
509 `libffi' is missing a few features.  We welcome patches to add support
510 for these.
511
512    * There is no support for calling varargs functions.  This may work
513      on some platforms, depending on how the ABI is defined, but it is
514      not reliable.
515
516    * There is no support for bit fields in structures.
517
518    * The closure API is
519
520    * The "raw" API is undocumented.
521
522 \1f
523 File: libffi.info,  Node: Index,  Prev: Missing Features,  Up: Top
524
525 Index
526 *****
527
528 \0\b[index\0\b]
529 * Menu:
530
531 * :                                      Structures.           (line 12)
532 * ABI:                                   Introduction.         (line 13)
533 * Application Binary Interface:          Introduction.         (line 13)
534 * calling convention:                    Introduction.         (line 13)
535 * cif:                                   The Basics.           (line 14)
536 * closure API:                           The Closure API.      (line 13)
537 * closures:                              The Closure API.      (line 13)
538 * FFI:                                   Introduction.         (line 31)
539 * ffi_call:                              The Basics.           (line 41)
540 * ffi_closure_alloc:                     The Closure API.      (line 19)
541 * ffi_closure_free:                      The Closure API.      (line 26)
542 * FFI_CLOSURES:                          The Closure API.      (line 13)
543 * ffi_prep_cif:                          The Basics.           (line 16)
544 * ffi_prep_closure_loc:                  The Closure API.      (line 34)
545 * ffi_status <1>:                        The Closure API.      (line 37)
546 * ffi_status:                            The Basics.           (line 18)
547 * ffi_type:                              Structures.           (line 11)
548 * ffi_type_double:                       Primitive Types.      (line 41)
549 * ffi_type_float:                        Primitive Types.      (line 38)
550 * ffi_type_longdouble:                   Primitive Types.      (line 71)
551 * ffi_type_pointer:                      Primitive Types.      (line 75)
552 * ffi_type_schar:                        Primitive Types.      (line 47)
553 * ffi_type_sint:                         Primitive Types.      (line 62)
554 * ffi_type_sint16:                       Primitive Types.      (line 23)
555 * ffi_type_sint32:                       Primitive Types.      (line 29)
556 * ffi_type_sint64:                       Primitive Types.      (line 35)
557 * ffi_type_sint8:                        Primitive Types.      (line 17)
558 * ffi_type_slong:                        Primitive Types.      (line 68)
559 * ffi_type_sshort:                       Primitive Types.      (line 56)
560 * ffi_type_uchar:                        Primitive Types.      (line 44)
561 * ffi_type_uint:                         Primitive Types.      (line 59)
562 * ffi_type_uint16:                       Primitive Types.      (line 20)
563 * ffi_type_uint32:                       Primitive Types.      (line 26)
564 * ffi_type_uint64:                       Primitive Types.      (line 32)
565 * ffi_type_uint8:                        Primitive Types.      (line 14)
566 * ffi_type_ulong:                        Primitive Types.      (line 65)
567 * ffi_type_ushort:                       Primitive Types.      (line 53)
568 * ffi_type_void:                         Primitive Types.      (line 10)
569 * Foreign Function Interface:            Introduction.         (line 31)
570 * void <1>:                              The Closure API.      (line 20)
571 * void:                                  The Basics.           (line 43)
572
573
574 \1f
575 Tag Table:
576 Node: Top\7f724
577 Node: Introduction\7f1466
578 Node: Using libffi\7f3102
579 Node: The Basics\7f3588
580 Node: Simple Example\7f6195
581 Node: Types\7f7222
582 Node: Primitive Types\7f7505
583 Node: Structures\7f9325
584 Node: Type Example\7f10185
585 Node: Multiple ABIs\7f11408
586 Node: The Closure API\7f11779
587 Node: Closure Example\7f14723
588 Node: Missing Features\7f16282
589 Node: Index\7f16775
590 \1f
591 End Tag Table