src/doc/nomicon/src/ffi.md

   1 # Foreign Function Interface
   2
   3 ## Introduction
   4
   5 This guide will use the [snappy](https://github.com/google/snappy)
   6 compression/decompression library as an introduction to writing bindings for
   7 foreign code. Rust is currently unable to call directly into a C++ library, but
   8 snappy includes a C interface (documented in
   9 [`snappy-c.h`](https://github.com/google/snappy/blob/master/snappy-c.h)).
  10
  11 ## A note about libc
  12
  13 Many of these examples use [the `libc` crate][libc], which provides various
  14 type definitions for C types, among other things. If you’re trying these
  15 examples yourself, you’ll need to add `libc` to your `Cargo.toml`:
  16
  17 ```toml
  18 [dependencies]
  19 libc = "0.2.0"
  20 ```
  21
  22 [libc]: https://crates.io/crates/libc
  23
  24 ## Calling foreign functions
  25
  26 The following is a minimal example of calling a foreign function which will
  27 compile if snappy is installed:
  28
  29 <!-- ignore: requires libc crate -->
  30 ```rust,ignore
  31 use libc::size_t;
  32
  33 #[link(name = "snappy")]
  34 extern {
  35     fn snappy_max_compressed_length(source_length: size_t) -> size_t;
  36 }
  37
  38 fn main() {
  39     let x = unsafe { snappy_max_compressed_length(100) };
  40     println!("max compressed length of a 100 byte buffer: {}", x);
  41 }
  42 ```
  43
  44 The `extern` block is a list of function signatures in a foreign library, in
  45 this case with the platform's C ABI. The `#[link(...)]` attribute is used to
  46 instruct the linker to link against the snappy library so the symbols are
  47 resolved.
  48
  49 Foreign functions are assumed to be unsafe so calls to them need to be wrapped
  50 with `unsafe {}` as a promise to the compiler that everything contained within
  51 truly is safe. C libraries often expose interfaces that aren't thread-safe, and
  52 almost any function that takes a pointer argument isn't valid for all possible
  53 inputs since the pointer could be dangling, and raw pointers fall outside of
  54 Rust's safe memory model.
  55
  56 When declaring the argument types to a foreign function, the Rust compiler
  57 cannot check if the declaration is correct, so specifying it correctly is part
  58 of keeping the binding correct at runtime.
  59
  60 The `extern` block can be extended to cover the entire snappy API:
  61
  62 <!-- ignore: requires libc crate -->
  63 ```rust,ignore
  64 use libc::{c_int, size_t};
  65
  66 #[link(name = "snappy")]
  67 extern {
  68     fn snappy_compress(input: *const u8,
  69                        input_length: size_t,
  70                        compressed: *mut u8,
  71                        compressed_length: *mut size_t) -> c_int;
  72     fn snappy_uncompress(compressed: *const u8,
  73                          compressed_length: size_t,
  74                          uncompressed: *mut u8,
  75                          uncompressed_length: *mut size_t) -> c_int;
  76     fn snappy_max_compressed_length(source_length: size_t) -> size_t;
  77     fn snappy_uncompressed_length(compressed: *const u8,
  78                                   compressed_length: size_t,
  79                                   result: *mut size_t) -> c_int;
  80     fn snappy_validate_compressed_buffer(compressed: *const u8,
  81                                          compressed_length: size_t) -> c_int;
  82 }
  83 # fn main() {}
  84 ```
  85
  86 ## Creating a safe interface
  87
  88 The raw C API needs to be wrapped to provide memory safety and make use of higher-level concepts
  89 like vectors. A library can choose to expose only the safe, high-level interface and hide the unsafe
  90 internal details.
  91
  92 Wrapping the functions which expect buffers involves using the `slice::raw` module to manipulate Rust
  93 vectors as pointers to memory. Rust's vectors are guaranteed to be a contiguous block of memory. The
  94 length is the number of elements currently contained, and the capacity is the total size in elements of
  95 the allocated memory. The length is less than or equal to the capacity.
  96
  97 <!-- ignore: requires libc crate -->
  98 ```rust,ignore
  99 # use libc::{c_int, size_t};
 100 # unsafe fn snappy_validate_compressed_buffer(_: *const u8, _: size_t) -> c_int { 0 }
 101 # fn main() {}
 102 pub fn validate_compressed_buffer(src: &[u8]) -> bool {
 103     unsafe {
 104         snappy_validate_compressed_buffer(src.as_ptr(), src.len() as size_t) == 0
 105     }
 106 }
 107 ```
 108
 109 The `validate_compressed_buffer` wrapper above makes use of an `unsafe` block, but it makes the
 110 guarantee that calling it is safe for all inputs by leaving off `unsafe` from the function
 111 signature.
 112
 113 The `snappy_compress` and `snappy_uncompress` functions are more complex, since a buffer has to be
 114 allocated to hold the output too.
 115
 116 The `snappy_max_compressed_length` function can be used to allocate a vector with the maximum
 117 required capacity to hold the compressed output. The vector can then be passed to the
 118 `snappy_compress` function as an output parameter. An output parameter is also passed to retrieve
 119 the true length after compression for setting the length.
 120
 121 <!-- ignore: requires libc crate -->
 122 ```rust,ignore
 123 # use libc::{size_t, c_int};
 124 # unsafe fn snappy_compress(a: *const u8, b: size_t, c: *mut u8,
 125 #                           d: *mut size_t) -> c_int { 0 }
 126 # unsafe fn snappy_max_compressed_length(a: size_t) -> size_t { a }
 127 # fn main() {}
 128 pub fn compress(src: &[u8]) -> Vec<u8> {
 129     unsafe {
 130         let srclen = src.len() as size_t;
 131         let psrc = src.as_ptr();
 132
 133         let mut dstlen = snappy_max_compressed_length(srclen);
 134         let mut dst = Vec::with_capacity(dstlen as usize);
 135         let pdst = dst.as_mut_ptr();
 136
 137         snappy_compress(psrc, srclen, pdst, &mut dstlen);
 138         dst.set_len(dstlen as usize);
 139         dst
 140     }
 141 }
 142 ```
 143
 144 Decompression is similar, because snappy stores the uncompressed size as part of the compression
 145 format and `snappy_uncompressed_length` will retrieve the exact buffer size required.
 146
 147 <!-- ignore: requires libc crate -->
 148 ```rust,ignore
 149 # use libc::{size_t, c_int};
 150 # unsafe fn snappy_uncompress(compressed: *const u8,
 151 #                             compressed_length: size_t,
 152 #                             uncompressed: *mut u8,
 153 #                             uncompressed_length: *mut size_t) -> c_int { 0 }
 154 # unsafe fn snappy_uncompressed_length(compressed: *const u8,
 155 #                                      compressed_length: size_t,
 156 #                                      result: *mut size_t) -> c_int { 0 }
 157 # fn main() {}
 158 pub fn uncompress(src: &[u8]) -> Option<Vec<u8>> {
 159     unsafe {
 160         let srclen = src.len() as size_t;
 161         let psrc = src.as_ptr();
 162
 163         let mut dstlen: size_t = 0;
 164         snappy_uncompressed_length(psrc, srclen, &mut dstlen);
 165
 166         let mut dst = Vec::with_capacity(dstlen as usize);
 167         let pdst = dst.as_mut_ptr();
 168
 169         if snappy_uncompress(psrc, srclen, pdst, &mut dstlen) == 0 {
 170             dst.set_len(dstlen as usize);
 171             Some(dst)
 172         } else {
 173             None // SNAPPY_INVALID_INPUT
 174         }
 175     }
 176 }
 177 ```
 178
 179 Then, we can add some tests to show how to use them.
 180
 181 <!-- ignore: requires libc crate -->
 182 ```rust,ignore
 183 # use libc::{c_int, size_t};
 184 # unsafe fn snappy_compress(input: *const u8,
 185 #                           input_length: size_t,
 186 #                           compressed: *mut u8,
 187 #                           compressed_length: *mut size_t)
 188 #                           -> c_int { 0 }
 189 # unsafe fn snappy_uncompress(compressed: *const u8,
 190 #                             compressed_length: size_t,
 191 #                             uncompressed: *mut u8,
 192 #                             uncompressed_length: *mut size_t)
 193 #                             -> c_int { 0 }
 194 # unsafe fn snappy_max_compressed_length(source_length: size_t) -> size_t { 0 }
 195 # unsafe fn snappy_uncompressed_length(compressed: *const u8,
 196 #                                      compressed_length: size_t,
 197 #                                      result: *mut size_t)
 198 #                                      -> c_int { 0 }
 199 # unsafe fn snappy_validate_compressed_buffer(compressed: *const u8,
 200 #                                             compressed_length: size_t)
 201 #                                             -> c_int { 0 }
 202 # fn main() { }
 203 #
 204 #[cfg(test)]
 205 mod tests {
 206     use super::*;
 207
 208     #[test]
 209     fn valid() {
 210         let d = vec![0xde, 0xad, 0xd0, 0x0d];
 211         let c: &[u8] = &compress(&d);
 212         assert!(validate_compressed_buffer(c));
 213         assert!(uncompress(c) == Some(d));
 214     }
 215
 216     #[test]
 217     fn invalid() {
 218         let d = vec![0, 0, 0, 0];
 219         assert!(!validate_compressed_buffer(&d));
 220         assert!(uncompress(&d).is_none());
 221     }
 222
 223     #[test]
 224     fn empty() {
 225         let d = vec![];
 226         assert!(!validate_compressed_buffer(&d));
 227         assert!(uncompress(&d).is_none());
 228         let c = compress(&d);
 229         assert!(validate_compressed_buffer(&c));
 230         assert!(uncompress(&c) == Some(d));
 231     }
 232 }
 233 ```
 234
 235 ## Destructors
 236
 237 Foreign libraries often hand off ownership of resources to the calling code.
 238 When this occurs, we must use Rust's destructors to provide safety and guarantee
 239 the release of these resources (especially in the case of panic).
 240
 241 For more about destructors, see the [Drop trait](../std/ops/trait.Drop.html).
 242
 243 ## Calling Rust code from C
 244
 245 You may wish to compile Rust code in a way so that it can be called from C.
 246 This is fairly easy, but requires a few things.
 247
 248 ### Rust side
 249
 250 First, we assume you have a lib crate named as `rust_from_c`.
 251 `lib.rs` should have Rust code as following:
 252
 253 ```rust
 254 #[no_mangle]
 255 pub extern "C" fn hello_from_rust() {
 256     println!("Hello from Rust!");
 257 }
 258 # fn main() {}
 259 ```
 260
 261 The `extern "C"` makes this function adhere to the C calling convention, as discussed above in "[Foreign Calling Conventions]".
 262 The `no_mangle` attribute turns off Rust's name mangling, so that it has a well defined symbol to link to.
 263
 264 Then, to compile Rust code as a shared library that can be called from C, add the following to your `Cargo.toml`:
 265
 266 ```toml
 267 [lib]
 268 crate-type = ["cdylib"]
 269 ```
 270
 271 (NOTE: We could also use the `staticlib` crate type but it needs to tweak some linking flags.)
 272
 273 Run `cargo build` and you're ready to go on the Rust side.
 274
 275 [Foreign Calling Conventions]: ffi.md#foreign-calling-conventions
 276
 277 ### C side
 278
 279 We'll create a C file to call the `hello_from_rust` function and compile it by `gcc`.
 280
 281 C file should look like:
 282
 283 ```c
 284 extern void hello_from_rust();
 285
 286 int main(void) {
 287     hello_from_rust();
 288     return 0;
 289 }
 290 ```
 291
 292 We name the file as `call_rust.c` and place it on the crate root.
 293 Run the following to compile:
 294
 295 ```sh
 296 gcc call_rust.c -o call_rust -lrust_from_c -L./target/debug
 297 ```
 298
 299 `-l` and `-L` tell gcc to find our Rust library.
 300
 301 Finally, we can call Rust code from C with `LD_LIBRARY_PATH` specified:
 302
 303 ```sh
 304 $ LD_LIBRARY_PATH=./target/debug ./call_rust
 305 Hello from Rust!
 306 ```
 307
 308 That's it!
 309 For more realistic example, check the [`cbindgen`].
 310
 311 [`cbindgen`]: https://github.com/eqrion/cbindgen
 312
 313 ## Callbacks from C code to Rust functions
 314
 315 Some external libraries require the usage of callbacks to report back their
 316 current state or intermediate data to the caller.
 317 It is possible to pass functions defined in Rust to an external library.
 318 The requirement for this is that the callback function is marked as `extern`
 319 with the correct calling convention to make it callable from C code.
 320
 321 The callback function can then be sent through a registration call
 322 to the C library and afterwards be invoked from there.
 323
 324 A basic example is:
 325
 326 Rust code:
 327
 328 ```rust,no_run
 329 extern fn callback(a: i32) {
 330     println!("I'm called from C with value {0}", a);
 331 }
 332
 333 #[link(name = "extlib")]
 334 extern {
 335    fn register_callback(cb: extern fn(i32)) -> i32;
 336    fn trigger_callback();
 337 }
 338
 339 fn main() {
 340     unsafe {
 341         register_callback(callback);
 342         trigger_callback(); // Triggers the callback.
 343     }
 344 }
 345 ```
 346
 347 C code:
 348
 349 ```c
 350 typedef void (*rust_callback)(int32_t);
 351 rust_callback cb;
 352
 353 int32_t register_callback(rust_callback callback) {
 354     cb = callback;
 355     return 1;
 356 }
 357
 358 void trigger_callback() {
 359   cb(7); // Will call callback(7) in Rust.
 360 }
 361 ```
 362
 363 In this example Rust's `main()` will call `trigger_callback()` in C,
 364 which would, in turn, call back to `callback()` in Rust.
 365
 366 ## Targeting callbacks to Rust objects
 367
 368 The former example showed how a global function can be called from C code.
 369 However it is often desired that the callback is targeted to a special
 370 Rust object. This could be the object that represents the wrapper for the
 371 respective C object.
 372
 373 This can be achieved by passing a raw pointer to the object down to the
 374 C library. The C library can then include the pointer to the Rust object in
 375 the notification. This will allow the callback to unsafely access the
 376 referenced Rust object.
 377
 378 Rust code:
 379
 380 ```rust,no_run
 381 struct RustObject {
 382     a: i32,
 383     // Other members...
 384 }
 385
 386 extern "C" fn callback(target: *mut RustObject, a: i32) {
 387     println!("I'm called from C with value {0}", a);
 388     unsafe {
 389         // Update the value in RustObject with the value received from the callback:
 390         (*target).a = a;
 391     }
 392 }
 393
 394 #[link(name = "extlib")]
 395 extern {
 396    fn register_callback(target: *mut RustObject,
 397                         cb: extern fn(*mut RustObject, i32)) -> i32;
 398    fn trigger_callback();
 399 }
 400
 401 fn main() {
 402     // Create the object that will be referenced in the callback:
 403     let mut rust_object = Box::new(RustObject { a: 5 });
 404
 405     unsafe {
 406         register_callback(&mut *rust_object, callback);
 407         trigger_callback();
 408     }
 409 }
 410 ```
 411
 412 C code:
 413
 414 ```c
 415 typedef void (*rust_callback)(void*, int32_t);
 416 void* cb_target;
 417 rust_callback cb;
 418
 419 int32_t register_callback(void* callback_target, rust_callback callback) {
 420     cb_target = callback_target;
 421     cb = callback;
 422     return 1;
 423 }
 424
 425 void trigger_callback() {
 426   cb(cb_target, 7); // Will call callback(&rustObject, 7) in Rust.
 427 }
 428 ```
 429
 430 ## Asynchronous callbacks
 431
 432 In the previously given examples the callbacks are invoked as a direct reaction
 433 to a function call to the external C library.
 434 The control over the current thread is switched from Rust to C to Rust for the
 435 execution of the callback, but in the end the callback is executed on the
 436 same thread that called the function which triggered the callback.
 437
 438 Things get more complicated when the external library spawns its own threads
 439 and invokes callbacks from there.
 440 In these cases access to Rust data structures inside the callbacks is
 441 especially unsafe and proper synchronization mechanisms must be used.
 442 Besides classical synchronization mechanisms like mutexes, one possibility in
 443 Rust is to use channels (in `std::sync::mpsc`) to forward data from the C
 444 thread that invoked the callback into a Rust thread.
 445
 446 If an asynchronous callback targets a special object in the Rust address space
 447 it is also absolutely necessary that no more callbacks are performed by the
 448 C library after the respective Rust object gets destroyed.
 449 This can be achieved by unregistering the callback in the object's
 450 destructor and designing the library in a way that guarantees that no
 451 callback will be performed after deregistration.
 452
 453 ## Linking
 454
 455 The `link` attribute on `extern` blocks provides the basic building block for
 456 instructing rustc how it will link to native libraries. There are two accepted
 457 forms of the link attribute today:
 458
 459 * `#[link(name = "foo")]`
 460 * `#[link(name = "foo", kind = "bar")]`
 461
 462 In both of these cases, `foo` is the name of the native library that we're
 463 linking to, and in the second case `bar` is the type of native library that the
 464 compiler is linking to. There are currently three known types of native
 465 libraries:
 466
 467 * Dynamic - `#[link(name = "readline")]`
 468 * Static - `#[link(name = "my_build_dependency", kind = "static")]`
 469 * Frameworks - `#[link(name = "CoreFoundation", kind = "framework")]`
 470
 471 Note that frameworks are only available on macOS targets.
 472
 473 The different `kind` values are meant to differentiate how the native library
 474 participates in linkage. From a linkage perspective, the Rust compiler creates
 475 two flavors of artifacts: partial (rlib/staticlib) and final (dylib/binary).
 476 Native dynamic library and framework dependencies are propagated to the final
 477 artifact boundary, while static library dependencies are not propagated at
 478 all, because the static libraries are integrated directly into the subsequent
 479 artifact.
 480
 481 A few examples of how this model can be used are:
 482
 483 * A native build dependency. Sometimes some C/C++ glue is needed when writing
 484   some Rust code, but distribution of the C/C++ code in a library format is
 485   a burden. In this case, the code will be archived into `libfoo.a` and then the
 486   Rust crate would declare a dependency via `#[link(name = "foo", kind =
 487   "static")]`.
 488
 489   Regardless of the flavor of output for the crate, the native static library
 490   will be included in the output, meaning that distribution of the native static
 491   library is not necessary.
 492
 493 * A normal dynamic dependency. Common system libraries (like `readline`) are
 494   available on a large number of systems, and often a static copy of these
 495   libraries cannot be found. When this dependency is included in a Rust crate,
 496   partial targets (like rlibs) will not link to the library, but when the rlib
 497   is included in a final target (like a binary), the native library will be
 498   linked in.
 499
 500 On macOS, frameworks behave with the same semantics as a dynamic library.
 501
 502 ## Unsafe blocks
 503
 504 Some operations, like dereferencing raw pointers or calling functions that have been marked
 505 unsafe are only allowed inside unsafe blocks. Unsafe blocks isolate unsafety and are a promise to
 506 the compiler that the unsafety does not leak out of the block.
 507
 508 Unsafe functions, on the other hand, advertise it to the world. An unsafe function is written like
 509 this:
 510
 511 ```rust
 512 unsafe fn kaboom(ptr: *const i32) -> i32 { *ptr }
 513 ```
 514
 515 This function can only be called from an `unsafe` block or another `unsafe` function.
 516
 517 ## Accessing foreign globals
 518
 519 Foreign APIs often export a global variable which could do something like track
 520 global state. In order to access these variables, you declare them in `extern`
 521 blocks with the `static` keyword:
 522
 523 <!-- ignore: requires libc crate -->
 524 ```rust,ignore
 525 #[link(name = "readline")]
 526 extern {
 527     static rl_readline_version: libc::c_int;
 528 }
 529
 530 fn main() {
 531     println!("You have readline version {} installed.",
 532              unsafe { rl_readline_version as i32 });
 533 }
 534 ```
 535
 536 Alternatively, you may need to alter global state provided by a foreign
 537 interface. To do this, statics can be declared with `mut` so we can mutate
 538 them.
 539
 540 <!-- ignore: requires libc crate -->
 541 ```rust,ignore
 542 use std::ffi::CString;
 543 use std::ptr;
 544
 545 #[link(name = "readline")]
 546 extern {
 547     static mut rl_prompt: *const libc::c_char;
 548 }
 549
 550 fn main() {
 551     let prompt = CString::new("[my-awesome-shell] $").unwrap();
 552     unsafe {
 553         rl_prompt = prompt.as_ptr();
 554
 555         println!("{:?}", rl_prompt);
 556
 557         rl_prompt = ptr::null();
 558     }
 559 }
 560 ```
 561
 562 Note that all interaction with a `static mut` is unsafe, both reading and
 563 writing. Dealing with global mutable state requires a great deal of care.
 564
 565 ## Foreign calling conventions
 566
 567 Most foreign code exposes a C ABI, and Rust uses the platform's C calling convention by default when
 568 calling foreign functions. Some foreign functions, most notably the Windows API, use other calling
 569 conventions. Rust provides a way to tell the compiler which convention to use:
 570
 571 <!-- ignore: requires libc crate -->
 572 ```rust,ignore
 573 #[cfg(all(target_os = "win32", target_arch = "x86"))]
 574 #[link(name = "kernel32")]
 575 #[allow(non_snake_case)]
 576 extern "stdcall" {
 577     fn SetEnvironmentVariableA(n: *const u8, v: *const u8) -> libc::c_int;
 578 }
 579 # fn main() { }
 580 ```
 581
 582 This applies to the entire `extern` block. The list of supported ABI constraints
 583 are:
 584
 585 * `stdcall`
 586 * `aapcs`
 587 * `cdecl`
 588 * `fastcall`
 589 * `vectorcall`
 590 This is currently hidden behind the `abi_vectorcall` gate and is subject to change.
 591 * `Rust`
 592 * `rust-intrinsic`
 593 * `system`
 594 * `C`
 595 * `win64`
 596 * `sysv64`
 597
 598 Most of the abis in this list are self-explanatory, but the `system` abi may
 599 seem a little odd. This constraint selects whatever the appropriate ABI is for
 600 interoperating with the target's libraries. For example, on win32 with a x86
 601 architecture, this means that the abi used would be `stdcall`. On x86_64,
 602 however, windows uses the `C` calling convention, so `C` would be used. This
 603 means that in our previous example, we could have used `extern "system" { ... }`
 604 to define a block for all windows systems, not only x86 ones.
 605
 606 ## Interoperability with foreign code
 607
 608 Rust guarantees that the layout of a `struct` is compatible with the platform's
 609 representation in C only if the `#[repr(C)]` attribute is applied to it.
 610 `#[repr(C, packed)]` can be used to lay out struct members without padding.
 611 `#[repr(C)]` can also be applied to an enum.
 612
 613 Rust's owned boxes (`Box<T>`) use non-nullable pointers as handles which point
 614 to the contained object. However, they should not be manually created because
 615 they are managed by internal allocators. References can safely be assumed to be
 616 non-nullable pointers directly to the type.  However, breaking the borrow
 617 checking or mutability rules is not guaranteed to be safe, so prefer using raw
 618 pointers (`*`) if that's needed because the compiler can't make as many
 619 assumptions about them.
 620
 621 Vectors and strings share the same basic memory layout, and utilities are
 622 available in the `vec` and `str` modules for working with C APIs. However,
 623 strings are not terminated with `\0`. If you need a NUL-terminated string for
 624 interoperability with C, you should use the `CString` type in the `std::ffi`
 625 module.
 626
 627 The [`libc` crate on crates.io][libc] includes type aliases and function
 628 definitions for the C standard library in the `libc` module, and Rust links
 629 against `libc` and `libm` by default.
 630
 631 ## Variadic functions
 632
 633 In C, functions can be 'variadic', meaning they accept a variable number of arguments. This can
 634 be achieved in Rust by specifying `...` within the argument list of a foreign function declaration:
 635
 636 ```no_run
 637 extern {
 638     fn foo(x: i32, ...);
 639 }
 640
 641 fn main() {
 642     unsafe {
 643         foo(10, 20, 30, 40, 50);
 644     }
 645 }
 646 ```
 647
 648 Normal Rust functions can *not* be variadic:
 649
 650 ```rust,compile_fail
 651 // This will not compile
 652
 653 fn foo(x: i32, ...) {}
 654 ```
 655
 656 ## The "nullable pointer optimization"
 657
 658 Certain Rust types are defined to never be `null`. This includes references (`&T`,
 659 `&mut T`), boxes (`Box<T>`), and function pointers (`extern "abi" fn()`). When
 660 interfacing with C, pointers that might be `null` are often used, which would seem to
 661 require some messy `transmute`s and/or unsafe code to handle conversions to/from Rust types.
 662 However, the language provides a workaround.
 663
 664 As a special case, an `enum` is eligible for the "nullable pointer optimization" if it contains
 665 exactly two variants, one of which contains no data and the other contains a field of one of the
 666 non-nullable types listed above.  This means no extra space is required for a discriminant; rather,
 667 the empty variant is represented by putting a `null` value into the non-nullable field. This is
 668 called an "optimization", but unlike other optimizations it is guaranteed to apply to eligible
 669 types.
 670
 671 The most common type that takes advantage of the nullable pointer optimization is `Option<T>`,
 672 where `None` corresponds to `null`. So `Option<extern "C" fn(c_int) -> c_int>` is a correct way
 673 to represent a nullable function pointer using the C ABI (corresponding to the C type
 674 `int (*)(int)`).
 675
 676 Here is a contrived example. Let's say some C library has a facility for registering a
 677 callback, which gets called in certain situations. The callback is passed a function pointer
 678 and an integer and it is supposed to run the function with the integer as a parameter. So
 679 we have function pointers flying across the FFI boundary in both directions.
 680
 681 <!-- ignore: requires libc crate -->
 682 ```rust,ignore
 683 use libc::c_int;
 684
 685 # #[cfg(hidden)]
 686 extern "C" {
 687     /// Registers the callback.
 688     fn register(cb: Option<extern "C" fn(Option<extern "C" fn(c_int) -> c_int>, c_int) -> c_int>);
 689 }
 690 # unsafe fn register(_: Option<extern "C" fn(Option<extern "C" fn(c_int) -> c_int>,
 691 #                                            c_int) -> c_int>)
 692 # {}
 693
 694 /// This fairly useless function receives a function pointer and an integer
 695 /// from C, and returns the result of calling the function with the integer.
 696 /// In case no function is provided, it squares the integer by default.
 697 extern "C" fn apply(process: Option<extern "C" fn(c_int) -> c_int>, int: c_int) -> c_int {
 698     match process {
 699         Some(f) => f(int),
 700         None    => int * int
 701     }
 702 }
 703
 704 fn main() {
 705     unsafe {
 706         register(Some(apply));
 707     }
 708 }
 709 ```
 710
 711 And the code on the C side looks like this:
 712
 713 ```c
 714 void register(int (*f)(int (*)(int), int)) {
 715     ...
 716 }
 717 ```
 718
 719 No `transmute` required!
 720
 721 ## FFI and unwinding
 722
 723 It’s important to be mindful of unwinding when working with FFI. Each
 724 non-`Rust` ABI comes in two variants, one with `-unwind` suffix and one without. If
 725 you expect Rust `panic`s or foreign (e.g. C++) exceptions to cross an FFI
 726 boundary, that boundary must use the appropriate `-unwind` ABI string (note
 727 that compiling with `panic=abort` will still cause `panic!` to immediately
 728 abort the process, regardless of which ABI is specified by the function that
 729 `panic`s).
 730
 731 Conversely, if you do not expect unwinding to cross an ABI boundary, use one of
 732 the non-`unwind` ABI strings (other than `Rust`, which always permits
 733 unwinding). If an unwinding operation does encounter an ABI boundary that is
 734 not permitted to unwind, the behavior depends on the source of the unwinding
 735 (Rust `panic` or a foreign exception):
 736
 737 * `panic` will cause the process to safely abort.
 738 * A foreign exception entering Rust will cause undefined behavior.
 739
 740 Note that the interaction of `catch_unwind` with foreign exceptions **is
 741 undefined**, as is the interaction of `panic` with foreign exception-catching
 742 mechanisms (notably C++'s `try`/`catch`).
 743
 744 ### Rust `panic` with `"C-unwind"`
 745
 746 <!-- ignore: using unstable feature -->
 747 ```rust,ignore
 748 #[no_mangle]
 749 extern "C-unwind" fn example() {
 750     panic!("Uh oh");
 751 }
 752 ```
 753
 754 This function (when compiled with `panic=unwind`) is permitted to unwind C++
 755 stack frames.
 756
 757 ```text
 758 [Rust function with `catch_unwind`, which stops the unwinding]
 759       |
 760      ...
 761       |
 762 [C++ frames]
 763       |                           ^
 764       | (calls)                   | (unwinding
 765       v                           |  goes this
 766 [Rust function `example`]         |  way)
 767       |                           |
 768       +--- rust function panics --+
 769 ```
 770
 771 If the C++ frames have objects, their destructors will be called.
 772
 773 ### C++ `throw` with `"C-unwind"`
 774
 775 <!-- ignore: using unstable feature -->
 776 ```rust,ignore
 777 #[link(...)]
 778 extern "C-unwind" {
 779     // A C++ function that may throw an exception
 780     fn may_throw();
 781 }
 782
 783 #[no_mangle]
 784 extern "C-unwind" fn rust_passthrough() {
 785     let b = Box::new(5);
 786     unsafe { may_throw(); }
 787     println!("{:?}", &b);
 788 }
 789 ```
 790
 791 A C++ function with a `try` block may invoke `rust_passthrough` and `catch` an
 792 exception thrown by `may_throw`.
 793
 794 ```text
 795 [C++ function with `try` block that invokes `rust_passthrough`]
 796       |
 797      ...
 798       |
 799 [Rust function `rust_passthrough`]
 800       |                            ^
 801       | (calls)                    | (unwinding
 802       v                            |  goes this
 803 [C++ function `may_throw`]         |  way)
 804       |                            |
 805       +--- C++ function throws ----+
 806 ```
 807
 808 If `may_throw` does throw an exception, `b` will be dropped. Otherwise, `5`
 809 will be printed.
 810
 811 ### `panic` can be stopped at an ABI boundary
 812
 813 ```rust
 814 #[no_mangle]
 815 extern "C" fn assert_nonzero(input: u32) {
 816     assert!(input != 0)
 817 }
 818 ```
 819
 820 If `assert_nonzero` is called with the argument `0`, the runtime is guaranteed
 821 to (safely) abort the process, whether or not compiled with `panic=abort`.
 822
 823 ### Catching `panic` preemptively
 824
 825 If you are writing Rust code that may panic, and you don't wish to abort the
 826 process if it panics, you must use [`catch_unwind`]:
 827
 828 ```rust
 829 use std::panic::catch_unwind;
 830
 831 #[no_mangle]
 832 pub extern "C" fn oh_no() -> i32 {
 833     let result = catch_unwind(|| {
 834         panic!("Oops!");
 835     });
 836     match result {
 837         Ok(_) => 0,
 838         Err(_) => 1,
 839     }
 840 }
 841
 842 fn main() {}
 843 ```
 844
 845 Please note that [`catch_unwind`] will only catch unwinding panics, not
 846 those that abort the process. See the documentation of [`catch_unwind`]
 847 for more information.
 848
 849 [`catch_unwind`]: ../std/panic/fn.catch_unwind.html
 850
 851 ## Representing opaque structs
 852
 853 Sometimes, a C library wants to provide a pointer to something, but not let you know the internal details of the thing it wants.
 854 A stable and simple way is to use a `void *` argument:
 855
 856 ```c
 857 void foo(void *arg);
 858 void bar(void *arg);
 859 ```
 860
 861 We can represent this in Rust with the `c_void` type:
 862
 863 <!-- ignore: requires libc crate -->
 864 ```rust,ignore
 865 extern "C" {
 866     pub fn foo(arg: *mut libc::c_void);
 867     pub fn bar(arg: *mut libc::c_void);
 868 }
 869 # fn main() {}
 870 ```
 871
 872 This is a perfectly valid way of handling the situation. However, we can do a bit
 873 better. To solve this, some C libraries will instead create a `struct`, where
 874 the details and memory layout of the struct are private. This gives some amount
 875 of type safety. These structures are called ‘opaque’. Here’s an example, in C:
 876
 877 ```c
 878 struct Foo; /* Foo is a structure, but its contents are not part of the public interface */
 879 struct Bar;
 880 void foo(struct Foo *arg);
 881 void bar(struct Bar *arg);
 882 ```
 883
 884 To do this in Rust, let’s create our own opaque types:
 885
 886 ```rust
 887 #[repr(C)]
 888 pub struct Foo {
 889     _data: [u8; 0],
 890     _marker:
 891         core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
 892 }
 893 #[repr(C)]
 894 pub struct Bar {
 895     _data: [u8; 0],
 896     _marker:
 897         core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
 898 }
 899
 900 extern "C" {
 901     pub fn foo(arg: *mut Foo);
 902     pub fn bar(arg: *mut Bar);
 903 }
 904 # fn main() {}
 905 ```
 906
 907 By including at least one private field and no constructor,
 908 we create an opaque type that we can't instantiate outside of this module.
 909 (A struct with no field could be instantiated by anyone.)
 910 We also want to use this type in FFI, so we have to add `#[repr(C)]`.
 911 The marker ensures the compiler does not mark the struct as `Send`, `Sync` and `Unpin` are
 912 not applied to the struct. (`*mut u8` is not `Send` or `Sync`, `PhantomPinned` is not `Unpin`)
 913
 914 But because our `Foo` and `Bar` types are
 915 different, we’ll get type safety between the two of them, so we cannot
 916 accidentally pass a pointer to `Foo` to `bar()`.
 917
 918 Notice that it is a really bad idea to use an empty enum as FFI type.
 919 The compiler relies on empty enums being uninhabited, so handling values of type
 920 `&Empty` is a huge footgun and can lead to buggy program behavior (by triggering
 921 undefined behavior).
 922
 923 > **NOTE:** The simplest way would use "extern types".
 924 But it's currently (as of June 2021) unstable and has some unresolved questions, see the [RFC page][extern-type-rfc] and the [tracking issue][extern-type-issue] for more details.
 925
 926 [extern-type-issue]: https://github.com/rust-lang/rust/issues/43467
 927 [extern-type-rfc]: https://rust-lang.github.io/rfcs/1861-extern-types.html