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