Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Application binary interface (ABI)

This section documents features that affect the ABI of the compiled output of a crate.

See extern functions for information on specifying the ABI for exporting functions. See external blocks for information on specifying the ABI for linking external libraries.

The used attribute

The used attribute forces a static to be kept in the output object file (.o, .rlib, etc., excluding final binaries) even if it’s never used or referenced by any other item in the crate. The linker, however, is still free to remove it.

Example

#![allow(unused)]
fn main() {
// lib.rs

// This is kept because of `#[used]`.
#[used]
static S1: u8 = 0;

// This is removable because it's unused.
#[allow(dead_code)]
static S2: u8 = 0;

// This is kept because it's publicly reachable.
pub static S3: u8 = 0;

// This is kept because it's referenced by a publicly
// reachable function.
static S4: u8 = 0;
#[unsafe(no_mangle)] pub fn f4() -> &'static u8 { &S4 }

// This is removable because it's referenced only by a
// private, unused (dead) function.
static S5: u8 = 0;
#[allow(dead_code)]
fn f5() -> &'static u8 { &S5 }
}
$ rustc -O --emit=obj --crate-type=rlib lib.rs
$ LC_ALL=C nm -C lib.o
0000000000000000 R lib::S1
0000000000000000 R lib::S3
0000000000000000 r lib::S4
0000000000000000 T f4

The used attribute uses the MetaWord syntax.

The used attribute may only be applied to static items.

Only the first use of used on an item has effect.

Note

rustc lints against any use following the first.

The no_mangle attribute

The no_mangle attribute disables the standard symbol name mangling on a function or static. The symbol for the item is the item’s identifier.

Example

#![allow(unused)]
fn main() {
#[unsafe(no_mangle)]
extern "C" fn foo() {}
}

The no_mangle attribute uses the MetaWord syntax.

The no_mangle attribute may only be applied to:

Note

rustc lints against use in other positions. This may become an error in the future.

The no_mangle attribute may not be used with a closure.

The no_mangle attribute may not be used on an item with generic parameters.

Only the first use of no_mangle on an item has effect.

Note

rustc lints against any use following the first.

When the no_mangle and export_name attributes are both applied to the same item, the symbol name from export_name is used, and no_mangle has no effect.

Note

rustc lints against this combination.

The no_mangle attribute must be marked with unsafe because an unmangled symbol may collide with another symbol with the same name (or with a well-known symbol), leading to undefined behavior.

2024 Edition differences

Before the 2024 edition, it is allowed to use the no_mangle attribute without unsafe.

In addition to disabling name mangling, the no_mangle attribute causes the symbol to be publicly exported from the produced library or object file, similar to the used attribute.

The no_mangle attribute may only be used on items with a name that contains only ASCII characters.

The link_section attribute specifies the section of the object file that a function or static’s content will be placed into.

The link_section attribute uses the MetaNameValueStr syntax to specify the section name.

#![allow(unused)]
fn main() {
#[cfg(target_os = "linux")] {
#[unsafe(no_mangle)]
#[unsafe(link_section = ".example_section")]
pub static VAR1: u32 = 1;
}
}

This attribute is unsafe as it allows users to place data and code into sections of memory not expecting them, such as mutable data into read-only areas.

Only the first use of link_section on an item has effect.

Note

rustc lints against any use following the first with a future-compatibility warning. This may become an error in the future.

2024 Edition differences

Before the 2024 edition it is allowed to use the link_section attribute without the unsafe qualification.

The export_name attribute

The export_name attribute specifies the name of the symbol that will be exported on a function or static.

The export_name attribute uses the MetaNameValueStr syntax to specify the symbol name.

#![allow(unused)]
fn main() {
#[unsafe(export_name = "exported_symbol_name")]
pub fn name_in_rust() { }
}

This attribute is unsafe as a symbol with a custom name may collide with another symbol with the same name (or with a well-known symbol), leading to undefined behavior.

Only the first use of export_name on an item has effect.

Note

rustc lints against any use following the first with a future-compatibility warning. This may become an error in the future.

2024 Edition differences

Before the 2024 edition it is allowed to use the export_name attribute without the unsafe qualification.