diff --git a/src/abi.md b/src/abi.md index cf183c0bf..c0f7ed78a 100644 --- a/src/abi.md +++ b/src/abi.md @@ -1,5 +1,7 @@ +r[abi] # Application Binary Interface (ABI) +r[abi.intro] This section documents features that affect the ABI of the compiled output of a crate. @@ -7,8 +9,10 @@ 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. +r[abi.used] ## The `used` attribute +r[abi.used.intro] The *`used` attribute* can only be applied to [`static` items]. This [attribute] forces the compiler to keep the variable in the output object file (.o, .rlib, etc. excluding final binaries) even if the variable is not used, or referenced, by any other item in the crate. @@ -57,15 +61,19 @@ $ nm -C foo.o 0000000000000000 T foo::quux ``` +r[abi.no_mangle] ## The `no_mangle` attribute +r[abi.no_mangle.intro] The *`no_mangle` attribute* may be used on any [item] to disable standard symbol name mangling. The symbol for the item will be the identifier of the item's name. +r[abi.no_mangle.publicly-exported] Additionally, the item will be publicly exported from the produced library or object file, similar to the [`used` attribute](#the-used-attribute). +r[abi.no_mangle.unsafe] This attribute is unsafe as an unmangled symbol may collide with another symbol with the same name (or with a well-known symbol), leading to undefined behavior. @@ -74,17 +82,19 @@ with the same name (or with a well-known symbol), leading to undefined behavior. extern "C" fn foo() {} ``` +r[abi.no_mangle.edition2024] > [!EDITION-2024] > Before the 2024 edition it is allowed to use the `no_mangle` attribute without the `unsafe` qualification. +r[abi.link_section] ## The `link_section` attribute +r[abi.link_section.intro] The *`link_section` attribute* specifies the section of the object file that a -[function] or [static]'s content will be placed into. It uses the -[MetaNameValueStr] syntax to specify the section name. +[function] or [static]'s content will be placed into. -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. +r[abi.link_section.syntax] +The `link_section` attribute uses the [MetaNameValueStr] syntax to specify the section name. ```rust,no_run @@ -93,24 +103,35 @@ of memory not expecting them, such as mutable data into read-only areas. pub static VAR1: u32 = 1; ``` +r[abi.link_section.unsafe] +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. + +r[abi.link_section.edition2024] > [!EDITION-2024] > Before the 2024 edition it is allowed to use the `link_section` attribute without the `unsafe` qualification. +r[abi.export_name] ## The `export_name` attribute +r[abi.export_name.intro] The *`export_name` attribute* specifies the name of the symbol that will be -exported on a [function] or [static]. It uses the [MetaNameValueStr] syntax -to specify the symbol name. +exported on a [function] or [static]. -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. +r[abi.export_name.syntax] +The `export_name `attribute uses the [MetaNameValueStr] syntax to specify the symbol name. ```rust #[unsafe(export_name = "exported_symbol_name")] pub fn name_in_rust() { } ``` +r[abi.export_name.unsafe] +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. + +r[abi.export_name.edition2024] > [!EDITION-2024] > Before the 2024 edition it is allowed to use the `export_name` attribute without the `unsafe` qualification.