Rust Reference ยท Attributes
The #[no_mangle] and #[export_name] attributes
Reference for Rust no_mangle and export_name: exporting functions and statics with a stable symbol name for FFI, and the unsafe(...) form required in edition 2024.
The Rust compiler normally mangles item names, so the symbol in the compiled object file looks like _ZN4demo3add17h4f...E. That keeps different crates and generic instantiations from colliding, but it also makes the function impossible to call from C by name.
#[no_mangle] keeps the plain name, and #[export_name = "x"] picks a specific one. Both are used for functions and statics that foreign code, or a plugin loader, needs to find. In edition 2024 they must be written as #[unsafe(no_mangle)] and #[unsafe(export_name = "...")], because a duplicate symbol can break the program in ways the compiler cannot check.
#[unsafe(no_mangle)] pub extern "C" fn add_ints(a: i32, b: i32) -> i32 { a + b }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
#[unsafe(no_mangle)] pub extern "C" fn name(args) -> ret { ... } #[unsafe(export_name = "symbol_name")] pub extern "C" fn other() { ... }
| Attribute | Effect |
|---|---|
#[unsafe(no_mangle)] |
The symbol is the item's own name, unmangled |
#[unsafe(export_name = "s")] |
The symbol is exactly s |
#[link_section = "..."] |
(related) places the item in a named section |
Before edition 2024 the forms #[no_mangle] and #[export_name = "x"] without unsafe(...) were accepted. In edition 2024 the unwrapped forms are an error.
Errors and edge cases:
- Two items exporting the same symbol name cause a link error, or silently pick one, depending on the platform.
- Generic functions cannot be
no_mangle, because there is no single symbol for them. - Use
extern "C"(or another stable ABI) on exported functions; Rust's default ABI is unspecified. - Items must be reachable (
pub) in a library crate built ascdylib,staticlibordylibto appear in the final binary.
Usage notes
- Crate type matters. Set
crate-type = ["cdylib"]or["staticlib"]inCargo.tomlto produce a library C can link to. This is not testable on the single-file runner. - Panics across the boundary. Unwinding out of an
extern "C"function aborts the process; catch panics at the boundary withstd::panic::catch_unwind. - Types. Stick to FFI-safe types: integers, raw pointers,
#[repr(C)]structs. Do not returnString,Vecor references to temporaries. - Name clashes. Prefix exported names (
mylib_add) so they do not collide with symbols from libc or other libraries. - Opposite direction. Calling C from Rust uses
unsafe extern "C" { ... }blocks; the attributes here are for exporting.
Related
#[repr],extern,unsafe- Lessons: FFI, Memory layout