1 % The Rust Foreign Function Interface Guide
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)).
11 The following is a minimal example of calling a foreign function which will
12 compile if snappy is installed:
18 #[link(name = "snappy")]
20 fn snappy_max_compressed_length(source_length: size_t) -> size_t;
24 let x = unsafe { snappy_max_compressed_length(100) };
25 println!("max compressed length of a 100 byte buffer: {}", x);
29 The `extern` block is a list of function signatures in a foreign library, in
30 this case with the platform's C ABI. The `#[link(...)]` attribute is used to
31 instruct the linker to link against the snappy library so the symbols are
34 Foreign functions are assumed to be unsafe so calls to them need to be wrapped
35 with `unsafe {}` as a promise to the compiler that everything contained within
36 truly is safe. C libraries often expose interfaces that aren't thread-safe, and
37 almost any function that takes a pointer argument isn't valid for all possible
38 inputs since the pointer could be dangling, and raw pointers fall outside of
39 Rust's safe memory model.
41 When declaring the argument types to a foreign function, the Rust compiler can
42 not check if the declaration is correct, so specifying it correctly is part of
43 keeping the binding correct at runtime.
45 The `extern` block can be extended to cover the entire snappy API:
49 use libc::{c_int, size_t};
51 #[link(name = "snappy")]
53 fn snappy_compress(input: *const u8,
56 compressed_length: *mut size_t) -> c_int;
57 fn snappy_uncompress(compressed: *const u8,
58 compressed_length: size_t,
59 uncompressed: *mut u8,
60 uncompressed_length: *mut size_t) -> c_int;
61 fn snappy_max_compressed_length(source_length: size_t) -> size_t;
62 fn snappy_uncompressed_length(compressed: *const u8,
63 compressed_length: size_t,
64 result: *mut size_t) -> c_int;
65 fn snappy_validate_compressed_buffer(compressed: *const u8,
66 compressed_length: size_t) -> c_int;
71 # Creating a safe interface
73 The raw C API needs to be wrapped to provide memory safety and make use of higher-level concepts
74 like vectors. A library can choose to expose only the safe, high-level interface and hide the unsafe
77 Wrapping the functions which expect buffers involves using the `slice::raw` module to manipulate Rust
78 vectors as pointers to memory. Rust's vectors are guaranteed to be a contiguous block of memory. The
79 length is number of elements currently contained, and the capacity is the total size in elements of
80 the allocated memory. The length is less than or equal to the capacity.
84 # use libc::{c_int, size_t};
85 # unsafe fn snappy_validate_compressed_buffer(_: *const u8, _: size_t) -> c_int { 0 }
87 pub fn validate_compressed_buffer(src: &[u8]) -> bool {
89 snappy_validate_compressed_buffer(src.as_ptr(), src.len() as size_t) == 0
94 The `validate_compressed_buffer` wrapper above makes use of an `unsafe` block, but it makes the
95 guarantee that calling it is safe for all inputs by leaving off `unsafe` from the function
98 The `snappy_compress` and `snappy_uncompress` functions are more complex, since a buffer has to be
99 allocated to hold the output too.
101 The `snappy_max_compressed_length` function can be used to allocate a vector with the maximum
102 required capacity to hold the compressed output. The vector can then be passed to the
103 `snappy_compress` function as an output parameter. An output parameter is also passed to retrieve
104 the true length after compression for setting the length.
108 # use libc::{size_t, c_int};
109 # unsafe fn snappy_compress(a: *const u8, b: size_t, c: *mut u8,
110 # d: *mut size_t) -> c_int { 0 }
111 # unsafe fn snappy_max_compressed_length(a: size_t) -> size_t { a }
113 pub fn compress(src: &[u8]) -> Vec<u8> {
115 let srclen = src.len() as size_t;
116 let psrc = src.as_ptr();
118 let mut dstlen = snappy_max_compressed_length(srclen);
119 let mut dst = Vec::with_capacity(dstlen as uint);
120 let pdst = dst.as_mut_ptr();
122 snappy_compress(psrc, srclen, pdst, &mut dstlen);
123 dst.set_len(dstlen as uint);
129 Decompression is similar, because snappy stores the uncompressed size as part of the compression
130 format and `snappy_uncompressed_length` will retrieve the exact buffer size required.
134 # use libc::{size_t, c_int};
135 # unsafe fn snappy_uncompress(compressed: *const u8,
136 # compressed_length: size_t,
137 # uncompressed: *mut u8,
138 # uncompressed_length: *mut size_t) -> c_int { 0 }
139 # unsafe fn snappy_uncompressed_length(compressed: *const u8,
140 # compressed_length: size_t,
141 # result: *mut size_t) -> c_int { 0 }
143 pub fn uncompress(src: &[u8]) -> Option<Vec<u8>> {
145 let srclen = src.len() as size_t;
146 let psrc = src.as_ptr();
148 let mut dstlen: size_t = 0;
149 snappy_uncompressed_length(psrc, srclen, &mut dstlen);
151 let mut dst = Vec::with_capacity(dstlen as uint);
152 let pdst = dst.as_mut_ptr();
154 if snappy_uncompress(psrc, srclen, pdst, &mut dstlen) == 0 {
155 dst.set_len(dstlen as uint);
158 None // SNAPPY_INVALID_INPUT
164 For reference, the examples used here are also available as an [library on
165 GitHub](https://github.com/thestinger/rust-snappy).
169 Rust tasks by default run on a "large stack". This is actually implemented as a
170 reserving a large segment of the address space and then lazily mapping in pages
171 as they are needed. When calling an external C function, the code is invoked on
172 the same stack as the rust stack. This means that there is no extra
173 stack-switching mechanism in place because it is assumed that the large stack
174 for the rust task is plenty for the C function to have.
176 A planned future improvement (not yet implemented at the time of this writing)
177 is to have a guard page at the end of every rust stack. No rust function will
178 hit this guard page (due to Rust's usage of LLVM's `__morestack`). The intention
179 for this unmapped page is to prevent infinite recursion in C from overflowing
180 onto other rust stacks. If the guard page is hit, then the process will be
181 terminated with a message saying that the guard page was hit.
183 For normal external function usage, this all means that there shouldn't be any
184 need for any extra effort on a user's perspective. The C stack naturally
185 interleaves with the rust stack, and it's "large enough" for both to
186 interoperate. If, however, it is determined that a larger stack is necessary,
187 there are appropriate functions in the task spawning API to control the size of
188 the stack of the task which is spawned.
192 Foreign libraries often hand off ownership of resources to the calling code.
193 When this occurs, we must use Rust's destructors to provide safety and guarantee
194 the release of these resources (especially in the case of panic).
196 # Callbacks from C code to Rust functions
198 Some external libraries require the usage of callbacks to report back their
199 current state or intermediate data to the caller.
200 It is possible to pass functions defined in Rust to an external library.
201 The requirement for this is that the callback function is marked as `extern`
202 with the correct calling convention to make it callable from C code.
204 The callback function can then be sent through a registration call
205 to the C library and afterwards be invoked from there.
212 extern fn callback(a: i32) {
213 println!("I'm called from C with value {0}", a);
216 #[link(name = "extlib")]
218 fn register_callback(cb: extern fn(i32)) -> i32;
219 fn trigger_callback();
224 register_callback(callback);
225 trigger_callback(); // Triggers the callback
233 typedef void (*rust_callback)(int32_t);
236 int32_t register_callback(rust_callback callback) {
241 void trigger_callback() {
242 cb(7); // Will call callback(7) in Rust
246 In this example Rust's `main()` will call `trigger_callback()` in C,
247 which would, in turn, call back to `callback()` in Rust.
250 ## Targeting callbacks to Rust objects
252 The former example showed how a global function can be called from C code.
253 However it is often desired that the callback is targeted to a special
254 Rust object. This could be the object that represents the wrapper for the
257 This can be achieved by passing an unsafe pointer to the object down to the
258 C library. The C library can then include the pointer to the Rust object in
259 the notification. This will allow the callback to unsafely access the
260 referenced Rust object.
265 # use std::boxed::Box;
273 extern "C" fn callback(target: *mut RustObject, a: i32) {
274 println!("I'm called from C with value {0}", a);
276 // Update the value in RustObject with the value received from the callback
281 #[link(name = "extlib")]
283 fn register_callback(target: *mut RustObject,
284 cb: extern fn(*mut RustObject, i32)) -> i32;
285 fn trigger_callback();
289 // Create the object that will be referenced in the callback
290 let mut rust_object = Box::new(RustObject { a: 5 });
293 register_callback(&mut *rust_object, callback);
302 typedef void (*rust_callback)(void*, int32_t);
306 int32_t register_callback(void* callback_target, rust_callback callback) {
307 cb_target = callback_target;
312 void trigger_callback() {
313 cb(cb_target, 7); // Will call callback(&rustObject, 7) in Rust
317 ## Asynchronous callbacks
319 In the previously given examples the callbacks are invoked as a direct reaction
320 to a function call to the external C library.
321 The control over the current thread is switched from Rust to C to Rust for the
322 execution of the callback, but in the end the callback is executed on the
323 same thread (and Rust task) that lead called the function which triggered
326 Things get more complicated when the external library spawns its own threads
327 and invokes callbacks from there.
328 In these cases access to Rust data structures inside the callbacks is
329 especially unsafe and proper synchronization mechanisms must be used.
330 Besides classical synchronization mechanisms like mutexes, one possibility in
331 Rust is to use channels (in `std::comm`) to forward data from the C thread
332 that invoked the callback into a Rust task.
334 If an asynchronous callback targets a special object in the Rust address space
335 it is also absolutely necessary that no more callbacks are performed by the
336 C library after the respective Rust object gets destroyed.
337 This can be achieved by unregistering the callback in the object's
338 destructor and designing the library in a way that guarantees that no
339 callback will be performed after deregistration.
343 The `link` attribute on `extern` blocks provides the basic building block for
344 instructing rustc how it will link to native libraries. There are two accepted
345 forms of the link attribute today:
347 * `#[link(name = "foo")]`
348 * `#[link(name = "foo", kind = "bar")]`
350 In both of these cases, `foo` is the name of the native library that we're
351 linking to, and in the second case `bar` is the type of native library that the
352 compiler is linking to. There are currently three known types of native
355 * Dynamic - `#[link(name = "readline")]`
356 * Static - `#[link(name = "my_build_dependency", kind = "static")]`
357 * Frameworks - `#[link(name = "CoreFoundation", kind = "framework")]`
359 Note that frameworks are only available on OSX targets.
361 The different `kind` values are meant to differentiate how the native library
362 participates in linkage. From a linkage perspective, the rust compiler creates
363 two flavors of artifacts: partial (rlib/staticlib) and final (dylib/binary).
364 Native dynamic libraries and frameworks are propagated to the final artifact
365 boundary, while static libraries are not propagated at all.
367 A few examples of how this model can be used are:
369 * A native build dependency. Sometimes some C/C++ glue is needed when writing
370 some rust code, but distribution of the C/C++ code in a library format is just
371 a burden. In this case, the code will be archived into `libfoo.a` and then the
372 rust crate would declare a dependency via `#[link(name = "foo", kind =
375 Regardless of the flavor of output for the crate, the native static library
376 will be included in the output, meaning that distribution of the native static
377 library is not necessary.
379 * A normal dynamic dependency. Common system libraries (like `readline`) are
380 available on a large number of systems, and often a static copy of these
381 libraries cannot be found. When this dependency is included in a rust crate,
382 partial targets (like rlibs) will not link to the library, but when the rlib
383 is included in a final target (like a binary), the native library will be
386 On OSX, frameworks behave with the same semantics as a dynamic library.
388 ## The `link_args` attribute
390 There is one other way to tell rustc how to customize linking, and that is via
391 the `link_args` attribute. This attribute is applied to `extern` blocks and
392 specifies raw flags which need to get passed to the linker when producing an
393 artifact. An example usage would be:
396 #![feature(link_args)]
398 #[link_args = "-foo -bar -baz"]
403 Note that this feature is currently hidden behind the `feature(link_args)` gate
404 because this is not a sanctioned way of performing linking. Right now rustc
405 shells out to the system linker, so it makes sense to provide extra command line
406 arguments, but this will not always be the case. In the future rustc may use
407 LLVM directly to link native libraries in which case `link_args` will have no
410 It is highly recommended to *not* use this attribute, and rather use the more
411 formal `#[link(...)]` attribute on `extern` blocks instead.
415 Some operations, like dereferencing unsafe pointers or calling functions that have been marked
416 unsafe are only allowed inside unsafe blocks. Unsafe blocks isolate unsafety and are a promise to
417 the compiler that the unsafety does not leak out of the block.
419 Unsafe functions, on the other hand, advertise it to the world. An unsafe function is written like
423 unsafe fn kaboom(ptr: *const int) -> int { *ptr }
426 This function can only be called from an `unsafe` block or another `unsafe` function.
428 # Accessing foreign globals
430 Foreign APIs often export a global variable which could do something like track
431 global state. In order to access these variables, you declare them in `extern`
432 blocks with the `static` keyword:
437 #[link(name = "readline")]
439 static rl_readline_version: libc::c_int;
443 println!("You have readline version {} installed.",
444 rl_readline_version as int);
448 Alternatively, you may need to alter global state provided by a foreign
449 interface. To do this, statics can be declared with `mut` so rust can mutate
455 use std::ffi::CString;
458 #[link(name = "readline")]
460 static mut rl_prompt: *const libc::c_char;
464 let prompt = CString::from_slice(b"[my-awesome-shell] $");
465 unsafe { rl_prompt = prompt.as_ptr(); }
466 // get a line, process it
467 unsafe { rl_prompt = ptr::null(); }
471 # Foreign calling conventions
473 Most foreign code exposes a C ABI, and Rust uses the platform's C calling convention by default when
474 calling foreign functions. Some foreign functions, most notably the Windows API, use other calling
475 conventions. Rust provides a way to tell the compiler which convention to use:
480 #[cfg(all(target_os = "win32", target_arch = "x86"))]
481 #[link(name = "kernel32")]
482 #[allow(non_snake_case)]
484 fn SetEnvironmentVariableA(n: *const u8, v: *const u8) -> libc::c_int;
489 This applies to the entire `extern` block. The list of supported ABI constraints
502 Most of the abis in this list are self-explanatory, but the `system` abi may
503 seem a little odd. This constraint selects whatever the appropriate ABI is for
504 interoperating with the target's libraries. For example, on win32 with a x86
505 architecture, this means that the abi used would be `stdcall`. On x86_64,
506 however, windows uses the `C` calling convention, so `C` would be used. This
507 means that in our previous example, we could have used `extern "system" { ... }`
508 to define a block for all windows systems, not just x86 ones.
510 # Interoperability with foreign code
512 Rust guarantees that the layout of a `struct` is compatible with the platform's
513 representation in C only if the `#[repr(C)]` attribute is applied to it.
514 `#[repr(C, packed)]` can be used to lay out struct members without padding.
515 `#[repr(C)]` can also be applied to an enum.
517 Rust's owned boxes (`Box<T>`) use non-nullable pointers as handles which point
518 to the contained object. However, they should not be manually created because
519 they are managed by internal allocators. References can safely be assumed to be
520 non-nullable pointers directly to the type. However, breaking the borrow
521 checking or mutability rules is not guaranteed to be safe, so prefer using raw
522 pointers (`*`) if that's needed because the compiler can't make as many
523 assumptions about them.
525 Vectors and strings share the same basic memory layout, and utilities are
526 available in the `vec` and `str` modules for working with C APIs. However,
527 strings are not terminated with `\0`. If you need a NUL-terminated string for
528 interoperability with C, you should use the `CString` type in the `std::ffi`
531 The standard library includes type aliases and function definitions for the C
532 standard library in the `libc` module, and Rust links against `libc` and `libm`
535 # The "nullable pointer optimization"
537 Certain types are defined to not be `null`. This includes references (`&T`,
538 `&mut T`), boxes (`Box<T>`), and function pointers (`extern "abi" fn()`).
539 When interfacing with C, pointers that might be null are often used.
540 As a special case, a generic `enum` that contains exactly two variants, one of
541 which contains no data and the other containing a single field, is eligible
542 for the "nullable pointer optimization". When such an enum is instantiated
543 with one of the non-nullable types, it is represented as a single pointer,
544 and the non-data variant is represented as the null pointer. So
545 `Option<extern "C" fn(c_int) -> c_int>` is how one represents a nullable
546 function pointer using the C ABI.