From c9d3bb566194125525ba08924e8afb8ce74d671a Mon Sep 17 00:00:00 2001 From: Amirhossein Akhlaghpour Date: Thu, 23 Jul 2026 12:12:25 +0330 Subject: [PATCH 1/2] docs: document symbol name attributes Signed-off-by: Amirhossein Akhlaghpour --- library/core/src/attribute_docs.rs | 76 ++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/library/core/src/attribute_docs.rs b/library/core/src/attribute_docs.rs index 584e1583c9bdb..2202a27cbeb42 100644 --- a/library/core/src/attribute_docs.rs +++ b/library/core/src/attribute_docs.rs @@ -633,3 +633,79 @@ const _: () = (); /// /// [the `non_exhaustive` attribute]: ../reference/attributes/type_system.html#the-non_exhaustive-attribute const _: () = (); +#[doc(attribute = "no_mangle")] +// +/// Exports an item without Rust symbol name mangling. +/// +/// Rust normally changes an item's symbol name to encode information such as its module path. +/// Applying `no_mangle` instead uses the item's identifier as the exported symbol name. +/// +/// ```rust +/// #[unsafe(no_mangle)] +/// pub extern "C" fn initialize() {} +/// ``` +/// +/// The attribute controls the symbol name and export behavior, but does not change the function's +/// calling convention. Functions intended to be called by non-Rust code will usually use an +/// appropriate `extern` ABI such as `extern "C"`. +/// +/// Exporting an unmangled name is unsafe because it may collide with another exported or +/// well-known symbol. Such a collision can lead to undefined behavior. +/// +/// Starting with the 2024 edition, the attribute must be written using the `unsafe(...)` syntax. +/// Earlier editions permit `#[no_mangle]`. +/// +/// For more information, see the Reference on [the `no_mangle` attribute]. +/// +/// [the `no_mangle` attribute]: ../reference/abi.html#the-no_mangle-attribute +const _: () = (); + +#[doc(attribute = "export_name")] +// +/// Exports a function or static under a chosen symbol name. +/// +/// The `export_name` attribute sets the symbol name that a function or static exposes in the +/// generated object file. The item's Rust name remains unchanged. +/// +/// ```rust +/// #[unsafe(export_name = "initialize")] +/// pub extern "C" fn initialize_library() {} +/// ``` +/// +/// Like [`no_mangle`], this attribute controls the exported symbol name but does not change the +/// function's calling convention. +/// +/// Choosing an exported name is unsafe because it can collide with another exported or +/// well-known symbol, which may cause undefined behavior. +/// +/// Starting with the 2024 edition, the attribute must be written using the `unsafe(...)` syntax. +/// Earlier editions permit `#[export_name = "..."]`. +/// +/// For more information, see the Reference on [the `export_name` attribute]. +/// +/// [`no_mangle`]: ./attribute.no_mangle.html +/// [the `export_name` attribute]: ../reference/abi.html#the-export_name-attribute +const _: () = (); + +#[doc(attribute = "link_name")] +// +/// Imports an external function or static using a different symbol name. +/// +/// The `link_name` attribute is applied to a declaration inside an `extern` block. It specifies +/// the symbol that the linker resolves for that declaration. +/// +/// ```rust,no_run +/// unsafe extern "C" { +/// #[link_name = "actual_symbol_name"] +/// fn name_in_rust(); +/// } +/// ``` +/// +/// In this example, Rust code uses `name_in_rust`, while the linker resolves +/// `actual_symbol_name`. The attribute can only be applied to function and static declarations +/// inside an `extern` block. +/// +/// For more information, see the Reference on [the `link_name` attribute]. +/// +/// [the `link_name` attribute]: ../reference/items/external-blocks.html#the-link_name-attribute +const _: () = (); From fcfaa976cccffac20c102ff3b72f794e85d5f79e Mon Sep 17 00:00:00 2001 From: Amirhossein Akhlaghpour Date: Tue, 1 Sep 2026 17:31:35 +0330 Subject: [PATCH 2/2] clarify symbol name attribute docs Signed-off-by: Amirhossein Akhlaghpour --- library/core/src/attribute_docs.rs | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/library/core/src/attribute_docs.rs b/library/core/src/attribute_docs.rs index 2202a27cbeb42..a01183253a5da 100644 --- a/library/core/src/attribute_docs.rs +++ b/library/core/src/attribute_docs.rs @@ -640,14 +640,15 @@ const _: () = (); /// Rust normally changes an item's symbol name to encode information such as its module path. /// Applying `no_mangle` instead uses the item's identifier as the exported symbol name. /// -/// ```rust +/// ``` /// #[unsafe(no_mangle)] -/// pub extern "C" fn initialize() {} +/// pub fn initialize() {} /// ``` /// -/// The attribute controls the symbol name and export behavior, but does not change the function's -/// calling convention. Functions intended to be called by non-Rust code will usually use an -/// appropriate `extern` ABI such as `extern "C"`. +/// In addition to disabling name mangling, `no_mangle` causes the symbol to be publicly exported +/// from the produced library or object file. It does not change the function's calling convention. +/// Functions intended to be called by non-Rust code will usually use an appropriate `extern` ABI +/// such as `extern "C"`. /// /// Exporting an unmangled name is unsafe because it may collide with another exported or /// well-known symbol. Such a collision can lead to undefined behavior. @@ -667,7 +668,7 @@ const _: () = (); /// The `export_name` attribute sets the symbol name that a function or static exposes in the /// generated object file. The item's Rust name remains unchanged. /// -/// ```rust +/// ``` /// #[unsafe(export_name = "initialize")] /// pub extern "C" fn initialize_library() {} /// ``` @@ -694,7 +695,7 @@ const _: () = (); /// The `link_name` attribute is applied to a declaration inside an `extern` block. It specifies /// the symbol that the linker resolves for that declaration. /// -/// ```rust,no_run +/// ```no_run /// unsafe extern "C" { /// #[link_name = "actual_symbol_name"] /// fn name_in_rust(); @@ -702,8 +703,8 @@ const _: () = (); /// ``` /// /// In this example, Rust code uses `name_in_rust`, while the linker resolves -/// `actual_symbol_name`. The attribute can only be applied to function and static declarations -/// inside an `extern` block. +/// `actual_symbol_name`. The attribute can only be applied to declarations of static variables and +/// of functions. /// /// For more information, see the Reference on [the `link_name` attribute]. ///