diff --git a/src/glossary.md b/src/glossary.md index fa5edee20..fd865dcc4 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -11,6 +11,14 @@ The alignment of a value specifies what addresses values are preferred to start at. Always a power of two. References to a value must be aligned. [More][alignment]. +r[glossary.abi] +### Application binary interface (ABI) + +An *application binary interface* (ABI) defines how compiled code interacts with other compiled code. With [`extern` blocks] and [`extern fn`], *ABI strings* affect: + +- **Calling convention**: How function arguments are passed, values are returned (e.g., in registers or on the stack), and who is responsible for cleaning up the stack. +- **Unwinding**: Whether stack unwinding is allowed. For example, the `"C-unwind"` ABI allows unwinding across the FFI boundary, while the `"C"` ABI does not. + ### Arity Arity refers to the number of arguments a function or operator takes. @@ -287,6 +295,8 @@ uninhabited type is "empty" in the sense that there are no values of the type. T example of an uninhabited type is the [never type] `!`, or an enum with no variants `enum Never { }`. Opposite of [Inhabited](#inhabited). +[`extern` blocks]: items.extern +[`extern fn`]: items.fn.extern [alignment]: type-layout.md#size-and-alignment [associated item]: #associated-item [attributes]: attributes.md diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index afe6d1945..25a265350 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -98,14 +98,21 @@ r[items.extern.abi] ## ABI r[items.extern.abi.intro] -By default external blocks assume that the library they are calling uses the -standard C ABI on the specific platform. Other ABIs may be specified using an -`abi` string, as shown here: +The `extern` keyword can be followed by an optional [ABI] string. The ABI specifies the calling convention of the functions in the block. The calling convention defines a low-level interface for functions, such as how arguments are placed in registers or on the stack, how return values are passed, and who is responsible for cleaning up the stack. -```rust -// Interface to the Windows API -unsafe extern "system" { } -``` +> [!EXAMPLE] +> ```rust +> // Interface to the Windows API. +> unsafe extern "system" { /* ... */ } +> ``` + +r[items.extern.abi.default] +If the ABI string is not specified, it defaults to `"C"`. + +> [!NOTE] +> The `extern` syntax without an explicit ABI is being phased out, so it's better to always write the ABI explicitly. +> +> For more details, see [Rust issue #134986](https://github.com/rust-lang/rust/issues/134986). r[items.extern.abi.standard] The following ABI strings are supported on all platforms: @@ -472,6 +479,7 @@ r[items.extern.attributes.fn-parameters] Attributes on extern function parameters follow the same rules and restrictions as [regular function parameters]. +[ABI]: glossary.abi [PE Format]: https://learn.microsoft.com/windows/win32/debug/pe-format#import-name-type [UEFI]: https://uefi.org/specifications [WebAssembly module]: https://webassembly.github.io/spec/core/syntax/modules.html