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 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 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 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 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 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 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 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 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 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 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 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 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 466 File: libffi.info, Node: Index, Prev: Missing Features, Up: Top 467 468 Index 469 ***** 470 471 [index] 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 518 Tag Table: 519 Node: Top688 520 Node: Introduction1424 521 Node: Using libffi3060 522 Node: The Basics3495 523 Node: Simple Example6102 524 Node: Types7129 525 Node: Primitive Types7412 526 Node: Structures9232 527 Node: Type Example10092 528 Node: Multiple ABIs11315 529 Node: The Closure API11686 530 Node: Missing Features14606 531 Node: Index15099 532 533 End Tag Table 534
