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