liveBook · Manning

No_mangle

As explained in Embedded Software with Rust

The Rust no_mangle attribute preserves an item's externally visible symbol name instead of applying name mangling.

Rust’s #[unsafe(no_mangle)] attribute preserves an item’s symbol name so a linker can find it by the name written in the source. Normally, Rust mangles names with information such as the crate and module, helping distinguish items that share a name. Using the attribute overrides the compiler’s usual management of symbol names, so the programmer must account for possible name collisions. section 8.1.1

For a function called from C, use no_mangle for the symbol name and extern "C" for the calling convention. These solve different problems: an unchanged name alone does not give a function the C calling convention. The pub keyword makes an item part of the public Rust API, but is not what exports its symbol to the C linker. section 8.3.1

#[unsafe(no_mangle)]
pub extern "C" fn add_one(x: u32) -> u32 {
    x.wrapping_add(1)
}

This function exposes the name add_one to C. wrapping_add makes overflow behavior explicit rather than allowing ordinary input to trigger an overflow panic. section 8.1.1

The attribute also applies to static data. If C refers to an immutable Rust static, declare it const on the C side: writing to immutable Rust data is invalid, and a static placed in flash may also fail at runtime if C tries to write to it. section 8.3.1

#[unsafe(no_mangle)]
pub static MAX_LIMIT: u32 = 1024;

The static keeps the symbol name MAX_LIMIT; C can reference it with an extern const declaration. section 8.3.1

In bare-metal startup, a linker may look for a conventional _start symbol when no entry point is supplied through other linker options. Preserving that name lets the linker find the custom entry function. Its extern "C" calling convention and diverging return type serve separate startup purposes. section 4.4.2

#[unsafe(no_mangle)]
pub unsafe extern "C" fn _start() -> ! {
    // Application initialization tasks
    // Just like the reset handler

    main();

    loop {}
}

This entry point retains the _start name, calls main, and loops rather than returning. section 4.4.2

For a vector table, no_mangle preserves a symbol name; link_section controls where the item is placed. When exporting a no_std static library, inspect the archive with nm and look for the plain function name to check that the symbol was not mangled. section 4.2.3 section 8.3.2

How Embedded Software with Rust covers it

How deep it goes
Explains name mangling and the attribute’s unsafe qualification, then distinguishes symbol naming from calling conventions and section placement.
Examples
Demonstrates a custom _start entry point, C-callable arithmetic functions, and an exported static constant.
What you can do after
Apply it to expose named symbols and verify an exported static-library function with nm.
How it connects
Connects name mangling with linkers, C calling conventions, static data, and vector tables.

Also explained in

Compare how 3 books explain no_mangle →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Embedded Software with Rust. The section links point to the parts of the book it draws on.