1This is libffi.info, produced by makeinfo version 6.6 from libffi.texi. 2 3This manual is for libffi, a portable foreign function interface 4library. 5 6 Copyright (C) 2008-2019 Anthony Green and Red Hat, Inc. 7 8 Permission is hereby granted, free of charge, to any person obtaining 9a copy of this software and associated documentation files (the 10"Software"), to deal in the Software without restriction, including 11without limitation the rights to use, copy, modify, merge, publish, 12distribute, sublicense, and/or sell copies of the Software, and to 13permit persons to whom the Software is furnished to do so, subject to 14the following conditions: 15 16 The above copyright notice and this permission notice shall be 17included in all copies or substantial portions of the Software. 18 19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 22IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 23CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 24TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 25SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 26 27INFO-DIR-SECTION Development 28START-INFO-DIR-ENTRY 29* libffi: (libffi). Portable foreign function interface library. 30END-INFO-DIR-ENTRY 31 32 33File: libffi.info, Node: Top, Next: Introduction, Up: (dir) 34 35libffi 36****** 37 38This manual is for libffi, a portable foreign function interface 39library. 40 41 Copyright (C) 2008-2019 Anthony Green and Red Hat, Inc. 42 43 Permission is hereby granted, free of charge, to any person obtaining 44a copy of this software and associated documentation files (the 45"Software"), to deal in the Software without restriction, including 46without limitation the rights to use, copy, modify, merge, publish, 47distribute, sublicense, and/or sell copies of the Software, and to 48permit persons to whom the Software is furnished to do so, subject to 49the following conditions: 50 51 The above copyright notice and this permission notice shall be 52included in all copies or substantial portions of the Software. 53 54 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 55EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 56MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 57IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 58CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 59TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 60SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 61 62* Menu: 63 64* Introduction:: What is libffi? 65* Using libffi:: How to use libffi. 66* Missing Features:: Things libffi can't do. 67* Index:: Index. 68 69 70File: libffi.info, Node: Introduction, Next: Using libffi, Prev: Top, Up: Top 71 721 What is libffi? 73***************** 74 75Compilers for high level languages generate code that follow certain 76conventions. These conventions are necessary, in part, for separate 77compilation to work. One such convention is the "calling convention". 78The calling convention is a set of assumptions made by the compiler 79about where function arguments will be found on entry to a function. A 80calling convention also specifies where the return value for a function 81is found. The calling convention is also sometimes called the "ABI" or 82"Application Binary Interface". 83 84 Some programs may not know at the time of compilation what arguments 85are to be passed to a function. For instance, an interpreter may be 86told at run-time about the number and types of arguments used to call a 87given function. 'Libffi' can be used in such programs to provide a 88bridge from the interpreter program to compiled code. 89 90 The 'libffi' library provides a portable, high level programming 91interface to various calling conventions. This allows a programmer to 92call any function specified by a call interface description at run time. 93 94 FFI stands for Foreign Function Interface. A foreign function 95interface is the popular name for the interface that allows code written 96in one language to call code written in another language. The 'libffi' 97library really only provides the lowest, machine dependent layer of a 98fully featured foreign function interface. A layer must exist above 99'libffi' that handles type conversions for values passed between the two 100languages. 101 102 103File: libffi.info, Node: Using libffi, Next: Missing Features, Prev: Introduction, Up: Top 104 1052 Using libffi 106************** 107 108* Menu: 109 110* The Basics:: The basic libffi API. 111* Simple Example:: A simple example. 112* Types:: libffi type descriptions. 113* Multiple ABIs:: Different passing styles on one platform. 114* The Closure API:: Writing a generic function. 115* Closure Example:: A closure example. 116* Thread Safety:: Thread safety. 117 118 119File: libffi.info, Node: The Basics, Next: Simple Example, Up: Using libffi 120 1212.1 The Basics 122============== 123 124'Libffi' assumes that you have a pointer to the function you wish to 125call and that you know the number and types of arguments to pass it, as 126well as the return type of the function. 127 128 The first thing you must do is create an 'ffi_cif' object that 129matches the signature of the function you wish to call. This is a 130separate step because it is common to make multiple calls using a single 131'ffi_cif'. The "cif" in 'ffi_cif' stands for Call InterFace. To 132prepare a call interface object, use the function 'ffi_prep_cif'. 133 134 -- Function: ffi_status ffi_prep_cif (ffi_cif *CIF, ffi_abi ABI, 135 unsigned int NARGS, ffi_type *RTYPE, ffi_type **ARGTYPES) 136 This initializes CIF according to the given parameters. 137 138 ABI is the ABI to use; normally 'FFI_DEFAULT_ABI' is what you want. 139 *note Multiple ABIs:: for more information. 140 141 NARGS is the number of arguments that this function accepts. 142 143 RTYPE is a pointer to an 'ffi_type' structure that describes the 144 return type of the function. *Note Types::. 145 146 ARGTYPES is a vector of 'ffi_type' pointers. ARGTYPES must have 147 NARGS elements. If NARGS is 0, this argument is ignored. 148 149 'ffi_prep_cif' returns a 'libffi' status code, of type 150 'ffi_status'. This will be either 'FFI_OK' if everything worked 151 properly; 'FFI_BAD_TYPEDEF' if one of the 'ffi_type' objects is 152 incorrect; or 'FFI_BAD_ABI' if the ABI parameter is invalid. 153 154 If the function being called is variadic (varargs) then 155'ffi_prep_cif_var' must be used instead of 'ffi_prep_cif'. 156 157 -- Function: ffi_status ffi_prep_cif_var (ffi_cif *CIF, ffi_abi ABI, 158 unsigned int NFIXEDARGS, unsigned int NTOTALARGS, ffi_type 159 *RTYPE, ffi_type **ARGTYPES) 160 This initializes CIF according to the given parameters for a call 161 to a variadic function. In general its operation is the same as 162 for 'ffi_prep_cif' except that: 163 164 NFIXEDARGS is the number of fixed arguments, prior to any variadic 165 arguments. It must be greater than zero. 166 167 NTOTALARGS the total number of arguments, including variadic and 168 fixed arguments. ARGTYPES must have this many elements. 169 170 Note that, different cif's must be prepped for calls to the same 171 function when different numbers of arguments are passed. 172 173 Also note that a call to 'ffi_prep_cif_var' with 174 NFIXEDARGS=NOTOTALARGS is NOT equivalent to a call to 175 'ffi_prep_cif'. 176 177 Note that the resulting 'ffi_cif' holds pointers to all the 178'ffi_type' objects that were used during initialization. You must 179ensure that these type objects have a lifetime at least as long as that 180of the 'ffi_cif'. 181 182 To call a function using an initialized 'ffi_cif', use the 'ffi_call' 183function: 184 185 -- Function: void ffi_call (ffi_cif *CIF, void *FN, void *RVALUE, void 186 **AVALUES) 187 This calls the function FN according to the description given in 188 CIF. CIF must have already been prepared using 'ffi_prep_cif'. 189 190 RVALUE is a pointer to a chunk of memory that will hold the result 191 of the function call. This must be large enough to hold the 192 result, no smaller than the system register size (generally 32 or 193 64 bits), and must be suitably aligned; it is the caller's 194 responsibility to ensure this. If CIF declares that the function 195 returns 'void' (using 'ffi_type_void'), then RVALUE is ignored. 196 197 In most situations, 'libffi' will handle promotion according to the 198 ABI. However, for historical reasons, there is a special case with 199 return values that must be handled by your code. In particular, 200 for integral (not 'struct') types that are narrower than the system 201 register size, the return value will be widened by 'libffi'. 202 'libffi' provides a type, 'ffi_arg', that can be used as the return 203 type. For example, if the CIF was defined with a return type of 204 'char', 'libffi' will try to store a full 'ffi_arg' into the return 205 value. 206 207 AVALUES is a vector of 'void *' pointers that point to the memory 208 locations holding the argument values for a call. If CIF declares 209 that the function has no arguments (i.e., NARGS was 0), then 210 AVALUES is ignored. Note that argument values may be modified by 211 the callee (for instance, structs passed by value); the burden of 212 copying pass-by-value arguments is placed on the caller. 213 214 Note that while the return value must be register-sized, arguments 215 should exactly match their declared type. For example, if an 216 argument is a 'short', then the entry in AVALUES should point to an 217 object declared as 'short'; but if the return type is 'short', then 218 RVALUE should point to an object declared as a larger type - 219 usually 'ffi_arg'. 220 221 222File: libffi.info, Node: Simple Example, Next: Types, Prev: The Basics, Up: Using libffi 223 2242.2 Simple Example 225================== 226 227Here is a trivial example that calls 'puts' a few times. 228 229 #include <stdio.h> 230 #include <ffi.h> 231 232 int main() 233 { 234 ffi_cif cif; 235 ffi_type *args[1]; 236 void *values[1]; 237 char *s; 238 ffi_arg rc; 239 240 /* Initialize the argument info vectors */ 241 args[0] = &ffi_type_pointer; 242 values[0] = &s; 243 244 /* Initialize the cif */ 245 if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, 246 &ffi_type_sint, args) == FFI_OK) 247 { 248 s = "Hello World!"; 249 ffi_call(&cif, puts, &rc, values); 250 /* rc now holds the result of the call to puts */ 251 252 /* values holds a pointer to the function's arg, so to 253 call puts() again all we need to do is change the 254 value of s */ 255 s = "This is cool!"; 256 ffi_call(&cif, puts, &rc, values); 257 } 258 259 return 0; 260 } 261 262 263File: libffi.info, Node: Types, Next: Multiple ABIs, Prev: Simple Example, Up: Using libffi 264 2652.3 Types 266========= 267 268* Menu: 269 270* Primitive Types:: Built-in types. 271* Structures:: Structure types. 272* Size and Alignment:: Size and alignment of types. 273* Arrays Unions Enums:: Arrays, unions, and enumerations. 274* Type Example:: Structure type example. 275* Complex:: Complex types. 276* Complex Type Example:: Complex type example. 277 278 279File: libffi.info, Node: Primitive Types, Next: Structures, Up: Types 280 2812.3.1 Primitive Types 282--------------------- 283 284'Libffi' provides a number of built-in type descriptors that can be used 285to describe argument and return types: 286 287'ffi_type_void' 288 The type 'void'. This cannot be used for argument types, only for 289 return values. 290 291'ffi_type_uint8' 292 An unsigned, 8-bit integer type. 293 294'ffi_type_sint8' 295 A signed, 8-bit integer type. 296 297'ffi_type_uint16' 298 An unsigned, 16-bit integer type. 299 300'ffi_type_sint16' 301 A signed, 16-bit integer type. 302 303'ffi_type_uint32' 304 An unsigned, 32-bit integer type. 305 306'ffi_type_sint32' 307 A signed, 32-bit integer type. 308 309'ffi_type_uint64' 310 An unsigned, 64-bit integer type. 311 312'ffi_type_sint64' 313 A signed, 64-bit integer type. 314 315'ffi_type_float' 316 The C 'float' type. 317 318'ffi_type_double' 319 The C 'double' type. 320 321'ffi_type_uchar' 322 The C 'unsigned char' type. 323 324'ffi_type_schar' 325 The C 'signed char' type. (Note that there is not an exact 326 equivalent to the C 'char' type in 'libffi'; ordinarily you should 327 either use 'ffi_type_schar' or 'ffi_type_uchar' depending on 328 whether 'char' is signed.) 329 330'ffi_type_ushort' 331 The C 'unsigned short' type. 332 333'ffi_type_sshort' 334 The C 'short' type. 335 336'ffi_type_uint' 337 The C 'unsigned int' type. 338 339'ffi_type_sint' 340 The C 'int' type. 341 342'ffi_type_ulong' 343 The C 'unsigned long' type. 344 345'ffi_type_slong' 346 The C 'long' type. 347 348'ffi_type_longdouble' 349 On platforms that have a C 'long double' type, this is defined. On 350 other platforms, it is not. 351 352'ffi_type_pointer' 353 A generic 'void *' pointer. You should use this for all pointers, 354 regardless of their real type. 355 356'ffi_type_complex_float' 357 The C '_Complex float' type. 358 359'ffi_type_complex_double' 360 The C '_Complex double' type. 361 362'ffi_type_complex_longdouble' 363 The C '_Complex long double' type. On platforms that have a C 364 'long double' type, this is defined. On other platforms, it is 365 not. 366 367 Each of these is of type 'ffi_type', so you must take the address 368when passing to 'ffi_prep_cif'. 369 370 371File: libffi.info, Node: Structures, Next: Size and Alignment, Prev: Primitive Types, Up: Types 372 3732.3.2 Structures 374---------------- 375 376'libffi' is perfectly happy passing structures back and forth. You must 377first describe the structure to 'libffi' by creating a new 'ffi_type' 378object for it. 379 380 -- Data type: ffi_type 381 The 'ffi_type' has the following members: 382 'size_t size' 383 This is set by 'libffi'; you should initialize it to zero. 384 385 'unsigned short alignment' 386 This is set by 'libffi'; you should initialize it to zero. 387 388 'unsigned short type' 389 For a structure, this should be set to 'FFI_TYPE_STRUCT'. 390 391 'ffi_type **elements' 392 This is a 'NULL'-terminated array of pointers to 'ffi_type' 393 objects. There is one element per field of the struct. 394 395 Note that 'libffi' has no special support for bit-fields. You 396 must manage these manually. 397 398 The 'size' and 'alignment' fields will be filled in by 'ffi_prep_cif' 399or 'ffi_prep_cif_var', as needed. 400 401 402File: libffi.info, Node: Size and Alignment, Next: Arrays Unions Enums, Prev: Structures, Up: Types 403 4042.3.3 Size and Alignment 405------------------------ 406 407'libffi' will set the 'size' and 'alignment' fields of an 'ffi_type' 408object for you. It does so using its knowledge of the ABI. 409 410 You might expect that you can simply read these fields for a type 411that has been laid out by 'libffi'. However, there are some caveats. 412 413 * The size or alignment of some of the built-in types may vary 414 depending on the chosen ABI. 415 416 * The size and alignment of a new structure type will not be set by 417 'libffi' until it has been passed to 'ffi_prep_cif' or 418 'ffi_get_struct_offsets'. 419 420 * A structure type cannot be shared across ABIs. Instead each ABI 421 needs its own copy of the structure type. 422 423 So, before examining these fields, it is safest to pass the 424'ffi_type' object to 'ffi_prep_cif' or 'ffi_get_struct_offsets' first. 425This function will do all the needed setup. 426 427 ffi_type *desired_type; 428 ffi_abi desired_abi; 429 ... 430 ffi_cif cif; 431 if (ffi_prep_cif (&cif, desired_abi, 0, desired_type, NULL) == FFI_OK) 432 { 433 size_t size = desired_type->size; 434 unsigned short alignment = desired_type->alignment; 435 } 436 437 'libffi' also provides a way to get the offsets of the members of a 438structure. 439 440 -- Function: ffi_status ffi_get_struct_offsets (ffi_abi abi, ffi_type 441 *struct_type, size_t *offsets) 442 Compute the offset of each element of the given structure type. 443 ABI is the ABI to use; this is needed because in some cases the 444 layout depends on the ABI. 445 446 OFFSETS is an out parameter. The caller is responsible for 447 providing enough space for all the results to be written - one 448 element per element type in STRUCT_TYPE. If OFFSETS is 'NULL', 449 then the type will be laid out but not otherwise modified. This 450 can be useful for accessing the type's size or layout, as mentioned 451 above. 452 453 This function returns 'FFI_OK' on success; 'FFI_BAD_ABI' if ABI is 454 invalid; or 'FFI_BAD_TYPEDEF' if STRUCT_TYPE is invalid in some 455 way. Note that only 'FFI_STRUCT' types are valid here. 456 457 458File: libffi.info, Node: Arrays Unions Enums, Next: Type Example, Prev: Size and Alignment, Up: Types 459 4602.3.4 Arrays, Unions, and Enumerations 461-------------------------------------- 462 4632.3.4.1 Arrays 464.............. 465 466'libffi' does not have direct support for arrays or unions. However, 467they can be emulated using structures. 468 469 To emulate an array, simply create an 'ffi_type' using 470'FFI_TYPE_STRUCT' with as many members as there are elements in the 471array. 472 473 ffi_type array_type; 474 ffi_type **elements 475 int i; 476 477 elements = malloc ((n + 1) * sizeof (ffi_type *)); 478 for (i = 0; i < n; ++i) 479 elements[i] = array_element_type; 480 elements[n] = NULL; 481 482 array_type.size = array_type.alignment = 0; 483 array_type.type = FFI_TYPE_STRUCT; 484 array_type.elements = elements; 485 486 Note that arrays cannot be passed or returned by value in C - 487structure types created like this should only be used to refer to 488members of real 'FFI_TYPE_STRUCT' objects. 489 490 However, a phony array type like this will not cause any errors from 491'libffi' if you use it as an argument or return type. This may be 492confusing. 493 4942.3.4.2 Unions 495.............. 496 497A union can also be emulated using 'FFI_TYPE_STRUCT'. In this case, 498however, you must make sure that the size and alignment match the real 499requirements of the union. 500 501 One simple way to do this is to ensue that each element type is laid 502out. Then, give the new structure type a single element; the size of 503the largest element; and the largest alignment seen as well. 504 505 This example uses the 'ffi_prep_cif' trick to ensure that each 506element type is laid out. 507 508 ffi_abi desired_abi; 509 ffi_type union_type; 510 ffi_type **union_elements; 511 512 int i; 513 ffi_type element_types[2]; 514 515 element_types[1] = NULL; 516 517 union_type.size = union_type.alignment = 0; 518 union_type.type = FFI_TYPE_STRUCT; 519 union_type.elements = element_types; 520 521 for (i = 0; union_elements[i]; ++i) 522 { 523 ffi_cif cif; 524 if (ffi_prep_cif (&cif, desired_abi, 0, union_elements[i], NULL) == FFI_OK) 525 { 526 if (union_elements[i]->size > union_type.size) 527 { 528 union_type.size = union_elements[i]; 529 size = union_elements[i]->size; 530 } 531 if (union_elements[i]->alignment > union_type.alignment) 532 union_type.alignment = union_elements[i]->alignment; 533 } 534 } 535 5362.3.4.3 Enumerations 537.................... 538 539'libffi' does not have any special support for C 'enum's. Although any 540given 'enum' is implemented using a specific underlying integral type, 541exactly which type will be used cannot be determined by 'libffi' - it 542may depend on the values in the enumeration or on compiler flags such as 543'-fshort-enums'. *Note (gcc)Structures unions enumerations and 544bit-fields implementation::, for more information about how GCC handles 545enumerations. 546 547 548File: libffi.info, Node: Type Example, Next: Complex, Prev: Arrays Unions Enums, Up: Types 549 5502.3.5 Type Example 551------------------ 552 553The following example initializes a 'ffi_type' object representing the 554'tm' struct from Linux's 'time.h'. 555 556 Here is how the struct is defined: 557 558 struct tm { 559 int tm_sec; 560 int tm_min; 561 int tm_hour; 562 int tm_mday; 563 int tm_mon; 564 int tm_year; 565 int tm_wday; 566 int tm_yday; 567 int tm_isdst; 568 /* Those are for future use. */ 569 long int __tm_gmtoff__; 570 __const char *__tm_zone__; 571 }; 572 573 Here is the corresponding code to describe this struct to 'libffi': 574 575 { 576 ffi_type tm_type; 577 ffi_type *tm_type_elements[12]; 578 int i; 579 580 tm_type.size = tm_type.alignment = 0; 581 tm_type.type = FFI_TYPE_STRUCT; 582 tm_type.elements = &tm_type_elements; 583 584 for (i = 0; i < 9; i++) 585 tm_type_elements[i] = &ffi_type_sint; 586 587 tm_type_elements[9] = &ffi_type_slong; 588 tm_type_elements[10] = &ffi_type_pointer; 589 tm_type_elements[11] = NULL; 590 591 /* tm_type can now be used to represent tm argument types and 592 return types for ffi_prep_cif() */ 593 } 594 595 596File: libffi.info, Node: Complex, Next: Complex Type Example, Prev: Type Example, Up: Types 597 5982.3.6 Complex Types 599------------------- 600 601'libffi' supports the complex types defined by the C99 standard 602('_Complex float', '_Complex double' and '_Complex long double' with the 603built-in type descriptors 'ffi_type_complex_float', 604'ffi_type_complex_double' and 'ffi_type_complex_longdouble'. 605 606 Custom complex types like '_Complex int' can also be used. An 607'ffi_type' object has to be defined to describe the complex type to 608'libffi'. 609 610 -- Data type: ffi_type 611 'size_t size' 612 This must be manually set to the size of the complex type. 613 614 'unsigned short alignment' 615 This must be manually set to the alignment of the complex 616 type. 617 618 'unsigned short type' 619 For a complex type, this must be set to 'FFI_TYPE_COMPLEX'. 620 621 'ffi_type **elements' 622 623 This is a 'NULL'-terminated array of pointers to 'ffi_type' 624 objects. The first element is set to the 'ffi_type' of the 625 complex's base type. The second element must be set to 626 'NULL'. 627 628 The section *note Complex Type Example:: shows a way to determine the 629'size' and 'alignment' members in a platform independent way. 630 631 For platforms that have no complex support in 'libffi' yet, the 632functions 'ffi_prep_cif' and 'ffi_prep_args' abort the program if they 633encounter a complex type. 634 635 636File: libffi.info, Node: Complex Type Example, Prev: Complex, Up: Types 637 6382.3.7 Complex Type Example 639-------------------------- 640 641This example demonstrates how to use complex types: 642 643 #include <stdio.h> 644 #include <ffi.h> 645 #include <complex.h> 646 647 void complex_fn(_Complex float cf, 648 _Complex double cd, 649 _Complex long double cld) 650 { 651 printf("cf=%f+%fi\ncd=%f+%fi\ncld=%f+%fi\n", 652 (float)creal (cf), (float)cimag (cf), 653 (float)creal (cd), (float)cimag (cd), 654 (float)creal (cld), (float)cimag (cld)); 655 } 656 657 int main() 658 { 659 ffi_cif cif; 660 ffi_type *args[3]; 661 void *values[3]; 662 _Complex float cf; 663 _Complex double cd; 664 _Complex long double cld; 665 666 /* Initialize the argument info vectors */ 667 args[0] = &ffi_type_complex_float; 668 args[1] = &ffi_type_complex_double; 669 args[2] = &ffi_type_complex_longdouble; 670 values[0] = &cf; 671 values[1] = &cd; 672 values[2] = &cld; 673 674 /* Initialize the cif */ 675 if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 3, 676 &ffi_type_void, args) == FFI_OK) 677 { 678 cf = 1.0 + 20.0 * I; 679 cd = 300.0 + 4000.0 * I; 680 cld = 50000.0 + 600000.0 * I; 681 /* Call the function */ 682 ffi_call(&cif, (void (*)(void))complex_fn, 0, values); 683 } 684 685 return 0; 686 } 687 688 This is an example for defining a custom complex type descriptor for 689compilers that support them: 690 691 /* 692 * This macro can be used to define new complex type descriptors 693 * in a platform independent way. 694 * 695 * name: Name of the new descriptor is ffi_type_complex_<name>. 696 * type: The C base type of the complex type. 697 */ 698 #define FFI_COMPLEX_TYPEDEF(name, type, ffitype) \ 699 static ffi_type *ffi_elements_complex_##name [2] = { \ 700 (ffi_type *)(&ffitype), NULL \ 701 }; \ 702 struct struct_align_complex_##name { \ 703 char c; \ 704 _Complex type x; \ 705 }; \ 706 ffi_type ffi_type_complex_##name = { \ 707 sizeof(_Complex type), \ 708 offsetof(struct struct_align_complex_##name, x), \ 709 FFI_TYPE_COMPLEX, \ 710 (ffi_type **)ffi_elements_complex_##name \ 711 } 712 713 /* Define new complex type descriptors using the macro: */ 714 /* ffi_type_complex_sint */ 715 FFI_COMPLEX_TYPEDEF(sint, int, ffi_type_sint); 716 /* ffi_type_complex_uchar */ 717 FFI_COMPLEX_TYPEDEF(uchar, unsigned char, ffi_type_uint8); 718 719 The new type descriptors can then be used like one of the built-in 720type descriptors in the previous example. 721 722 723File: libffi.info, Node: Multiple ABIs, Next: The Closure API, Prev: Types, Up: Using libffi 724 7252.4 Multiple ABIs 726================= 727 728A given platform may provide multiple different ABIs at once. For 729instance, the x86 platform has both 'stdcall' and 'fastcall' functions. 730 731 'libffi' provides some support for this. However, this is 732necessarily platform-specific. 733 734 735File: libffi.info, Node: The Closure API, Next: Closure Example, Prev: Multiple ABIs, Up: Using libffi 736 7372.5 The Closure API 738=================== 739 740'libffi' also provides a way to write a generic function - a function 741that can accept and decode any combination of arguments. This can be 742useful when writing an interpreter, or to provide wrappers for arbitrary 743functions. 744 745 This facility is called the "closure API". Closures are not supported 746on all platforms; you can check the 'FFI_CLOSURES' define to determine 747whether they are supported on the current platform. 748 749 Because closures work by assembling a tiny function at runtime, they 750require special allocation on platforms that have a non-executable heap. 751Memory management for closures is handled by a pair of functions: 752 753 -- Function: void *ffi_closure_alloc (size_t SIZE, void **CODE) 754 Allocate a chunk of memory holding SIZE bytes. This returns a 755 pointer to the writable address, and sets *CODE to the 756 corresponding executable address. 757 758 SIZE should be sufficient to hold a 'ffi_closure' object. 759 760 -- Function: void ffi_closure_free (void *WRITABLE) 761 Free memory allocated using 'ffi_closure_alloc'. The argument is 762 the writable address that was returned. 763 764 Once you have allocated the memory for a closure, you must construct 765a 'ffi_cif' describing the function call. Finally you can prepare the 766closure function: 767 768 -- Function: ffi_status ffi_prep_closure_loc (ffi_closure *CLOSURE, 769 ffi_cif *CIF, void (*FUN) (ffi_cif *CIF, void *RET, void 770 **ARGS, void *USER_DATA), void *USER_DATA, void *CODELOC) 771 Prepare a closure function. The arguments to 772 'ffi_prep_closure_loc' are: 773 774 CLOSURE 775 The address of a 'ffi_closure' object; this is the writable 776 address returned by 'ffi_closure_alloc'. 777 778 CIF 779 The 'ffi_cif' describing the function parameters. Note that 780 this object, and the types to which it refers, must be kept 781 alive until the closure itself is freed. 782 783 USER_DATA 784 An arbitrary datum that is passed, uninterpreted, to your 785 closure function. 786 787 CODELOC 788 The executable address returned by 'ffi_closure_alloc'. 789 790 FUN 791 The function which will be called when the closure is invoked. 792 It is called with the arguments: 793 794 CIF 795 The 'ffi_cif' passed to 'ffi_prep_closure_loc'. 796 797 RET 798 A pointer to the memory used for the function's return 799 value. 800 801 If the function is declared as returning 'void', then 802 this value is garbage and should not be used. 803 804 Otherwise, FUN must fill the object to which this points, 805 following the same special promotion behavior as 806 'ffi_call'. That is, in most cases, RET points to an 807 object of exactly the size of the type specified when CIF 808 was constructed. However, integral types narrower than 809 the system register size are widened. In these cases 810 your program may assume that RET points to an 'ffi_arg' 811 object. 812 813 ARGS 814 A vector of pointers to memory holding the arguments to 815 the function. 816 817 USER_DATA 818 The same USER_DATA that was passed to 819 'ffi_prep_closure_loc'. 820 821 'ffi_prep_closure_loc' will return 'FFI_OK' if everything went ok, 822 and one of the other 'ffi_status' values on error. 823 824 After calling 'ffi_prep_closure_loc', you can cast CODELOC to the 825 appropriate pointer-to-function type. 826 827 You may see old code referring to 'ffi_prep_closure'. This function 828is deprecated, as it cannot handle the need for separate writable and 829executable addresses. 830 831 832File: libffi.info, Node: Closure Example, Next: Thread Safety, Prev: The Closure API, Up: Using libffi 833 8342.6 Closure Example 835=================== 836 837A trivial example that creates a new 'puts' by binding 'fputs' with 838'stdout'. 839 840 #include <stdio.h> 841 #include <ffi.h> 842 843 /* Acts like puts with the file given at time of enclosure. */ 844 void puts_binding(ffi_cif *cif, void *ret, void* args[], 845 void *stream) 846 { 847 *(ffi_arg *)ret = fputs(*(char **)args[0], (FILE *)stream); 848 } 849 850 typedef int (*puts_t)(char *); 851 852 int main() 853 { 854 ffi_cif cif; 855 ffi_type *args[1]; 856 ffi_closure *closure; 857 858 void *bound_puts; 859 int rc; 860 861 /* Allocate closure and bound_puts */ 862 closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts); 863 864 if (closure) 865 { 866 /* Initialize the argument info vectors */ 867 args[0] = &ffi_type_pointer; 868 869 /* Initialize the cif */ 870 if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, 871 &ffi_type_sint, args) == FFI_OK) 872 { 873 /* Initialize the closure, setting stream to stdout */ 874 if (ffi_prep_closure_loc(closure, &cif, puts_binding, 875 stdout, bound_puts) == FFI_OK) 876 { 877 rc = ((puts_t)bound_puts)("Hello World!"); 878 /* rc now holds the result of the call to fputs */ 879 } 880 } 881 } 882 883 /* Deallocate both closure, and bound_puts */ 884 ffi_closure_free(closure); 885 886 return 0; 887 } 888 889 890 891File: libffi.info, Node: Thread Safety, Prev: Closure Example, Up: Using libffi 892 8932.7 Thread Safety 894================= 895 896'libffi' is not completely thread-safe. However, many parts are, and if 897you follow some simple rules, you can use it safely in a multi-threaded 898program. 899 900 * 'ffi_prep_cif' may modify the 'ffi_type' objects passed to it. It 901 is best to ensure that only a single thread prepares a given 902 'ffi_cif' at a time. 903 904 * On some platforms, 'ffi_prep_cif' may modify the size and alignment 905 of some types, depending on the chosen ABI. On these platforms, if 906 you switch between ABIs, you must ensure that there is only one 907 call to 'ffi_prep_cif' at a time. 908 909 Currently the only affected platform is PowerPC and the only 910 affected type is 'long double'. 911 912 913File: libffi.info, Node: Missing Features, Next: Index, Prev: Using libffi, Up: Top 914 9153 Missing Features 916****************** 917 918'libffi' is missing a few features. We welcome patches to add support 919for these. 920 921 * Variadic closures. 922 923 * There is no support for bit fields in structures. 924 925 * The "raw" API is undocumented. 926 927 * The Go API is undocumented. 928 929 Note that variadic support is very new and tested on a relatively 930small number of platforms. 931 932 933File: libffi.info, Node: Index, Prev: Missing Features, Up: Top 934 935Index 936***** 937 938�[index�] 939* Menu: 940 941* ABI: Introduction. (line 13) 942* Application Binary Interface: Introduction. (line 13) 943* calling convention: Introduction. (line 13) 944* cif: The Basics. (line 14) 945* closure API: The Closure API. (line 13) 946* closures: The Closure API. (line 13) 947* FFI: Introduction. (line 31) 948* ffi_call: The Basics. (line 67) 949* FFI_CLOSURES: The Closure API. (line 13) 950* ffi_closure_alloc: The Closure API. (line 19) 951* ffi_closure_free: The Closure API. (line 26) 952* ffi_get_struct_offsets: Size and Alignment. (line 39) 953* ffi_prep_cif: The Basics. (line 16) 954* ffi_prep_cif_var: The Basics. (line 39) 955* ffi_prep_closure_loc: The Closure API. (line 34) 956* ffi_status: The Basics. (line 16) 957* ffi_status <1>: The Basics. (line 39) 958* ffi_status <2>: Size and Alignment. (line 39) 959* ffi_status <3>: The Closure API. (line 34) 960* ffi_type: Structures. (line 10) 961* ffi_type <1>: Structures. (line 10) 962* ffi_type <2>: Complex. (line 15) 963* ffi_type <3>: Complex. (line 15) 964* ffi_type_complex_double: Primitive Types. (line 82) 965* ffi_type_complex_float: Primitive Types. (line 79) 966* ffi_type_complex_longdouble: Primitive Types. (line 85) 967* ffi_type_double: Primitive Types. (line 41) 968* ffi_type_float: Primitive Types. (line 38) 969* ffi_type_longdouble: Primitive Types. (line 71) 970* ffi_type_pointer: Primitive Types. (line 75) 971* ffi_type_schar: Primitive Types. (line 47) 972* ffi_type_sint: Primitive Types. (line 62) 973* ffi_type_sint16: Primitive Types. (line 23) 974* ffi_type_sint32: Primitive Types. (line 29) 975* ffi_type_sint64: Primitive Types. (line 35) 976* ffi_type_sint8: Primitive Types. (line 17) 977* ffi_type_slong: Primitive Types. (line 68) 978* ffi_type_sshort: Primitive Types. (line 56) 979* ffi_type_uchar: Primitive Types. (line 44) 980* ffi_type_uint: Primitive Types. (line 59) 981* ffi_type_uint16: Primitive Types. (line 20) 982* ffi_type_uint32: Primitive Types. (line 26) 983* ffi_type_uint64: Primitive Types. (line 32) 984* ffi_type_uint8: Primitive Types. (line 14) 985* ffi_type_ulong: Primitive Types. (line 65) 986* ffi_type_ushort: Primitive Types. (line 53) 987* ffi_type_void: Primitive Types. (line 10) 988* Foreign Function Interface: Introduction. (line 31) 989* void: The Basics. (line 67) 990* void <1>: The Closure API. (line 19) 991* void <2>: The Closure API. (line 26) 992 993 994 995Tag Table: 996Node: Top1388 997Node: Introduction2841 998Node: Using libffi4473 999Node: The Basics5006 1000Node: Simple Example9870 1001Node: Types10901 1002Node: Primitive Types11412 1003Node: Structures13533 1004Node: Size and Alignment14572 1005Node: Arrays Unions Enums16769 1006Node: Type Example19698 1007Node: Complex20989 1008Node: Complex Type Example22407 1009Node: Multiple ABIs25459 1010Node: The Closure API25830 1011Node: Closure Example29656 1012Node: Thread Safety31288 1013Node: Missing Features32089 1014Node: Index32551 1015 1016End Tag Table 1017