From fa690b6554546e97d7782ba26b07fc8062e6898a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:52:40 -0700 Subject: [PATCH 1/4] Move example to example block --- src/items/external-blocks.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 6fdb70028f..7bec80e3d3 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -429,14 +429,15 @@ The *`link_ordinal` attribute* can be applied on declarations inside an `extern` > [!WARNING] > `link_ordinal` should only be used in cases where the ordinal of the symbol is known to be stable: if the ordinal of a symbol is not explicitly set when its containing binary is built then one will be automatically assigned to it, and that assigned ordinal may change between builds of the binary. -```rust -# #[cfg(all(windows, target_arch = "x86"))] -#[link(name = "exporter", kind = "raw-dylib")] -unsafe extern "stdcall" { - #[link_ordinal(15)] - safe fn imported_function_stdcall(i: i32); -} -``` +> [!EXAMPLE] +> ```rust +> # #[cfg(all(windows, target_arch = "x86"))] +> #[link(name = "exporter", kind = "raw-dylib")] +> unsafe extern "stdcall" { +> #[link_ordinal(15)] +> safe fn imported_function_stdcall(i: i32); +> } +> ``` r[items.extern.attributes.link_ordinal.allowed-kinds] This attribute is only used with the `raw-dylib` linking kind. Using any other kind will result in a compiler error. From fb23bb7fc9e1dead268c141008efde1850ae9074 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:52:51 -0700 Subject: [PATCH 2/4] Linkify "attribute" --- src/items/external-blocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 7bec80e3d3..3a71716277 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -424,7 +424,7 @@ r[items.extern.attributes.link_ordinal] ### The `link_ordinal` attribute r[items.extern.attributes.link_ordinal.intro] -The *`link_ordinal` attribute* can be applied on declarations inside an `extern` block to indicate the numeric ordinal to use when generating the import library to link against. An ordinal is a unique number per symbol exported by a dynamic library on Windows and can be used when the library is being loaded to find that symbol rather than having to look it up by name. +The *`link_ordinal` [attribute][attributes]* can be applied on declarations inside an `extern` block to indicate the numeric ordinal to use when generating the import library to link against. An ordinal is a unique number per symbol exported by a dynamic library on Windows and can be used when the library is being loaded to find that symbol rather than having to look it up by name. > [!WARNING] > `link_ordinal` should only be used in cases where the ordinal of the symbol is known to be stable: if the ordinal of a symbol is not explicitly set when its containing binary is built then one will be automatically assigned to it, and that assigned ordinal may change between builds of the binary. From 24154e609fd42410bed1c47d062f3997f5367646 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:55:00 -0700 Subject: [PATCH 3/4] Update link_ordinal to use the attribute template --- src/items/external-blocks.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 3a71716277..8243ca510e 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -439,11 +439,29 @@ The *`link_ordinal` [attribute][attributes]* can be applied on declarations insi > } > ``` +r[items.extern.attributes.link_ordinal.syntax] +The syntax for the `link_ordinal` attribute is: + +```grammar,attributes +@root LinkOrdinalAttribute -> `link_ordinal` `(` LinkOrdinal `)` + +LinkOrdinal -> DEC_LITERAL | BIN_LITERAL | OCT_LITERAL | HEX_LITERAL +``` + +r[items.extern.attributes.link_ordinal.max] +The ordinal must be less than or equal to [`u16::MAX`]. + +r[items.extern.attributes.link_ordinal.allowed-positions] +The `link_ordinal` attribute may be specified on a function or static in an `extern` block. + +r[items.extern.attributes.link_ordinal.duplicates] +The `link_ordinal` attribute may only be specified once on an item. + r[items.extern.attributes.link_ordinal.allowed-kinds] -This attribute is only used with the `raw-dylib` linking kind. Using any other kind will result in a compiler error. +The `link_ordinal` attribute may only be used with the [`raw-dylib` linking kind][items.extern.attributes.link.raw-dylib]. -r[items.extern.attributes.link_ordinal.exclusive] -Using this attribute with the `link_name` attribute will result in a compiler error. +r[items.extern.attributes.link_ordinal.link_name] +The `link_ordinal` attribute may not be used with the [`link_name`] attribute. r[items.extern.attributes.fn-parameters] ### Attributes on function parameters @@ -457,6 +475,8 @@ Attributes on extern function parameters follow the same rules and restrictions [`bundle` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-bundle [`dylib` versus `raw-dylib`]: #dylib-versus-raw-dylib [`extern fn`]: items.fn.extern +[`link_name`]: items.extern.attributes.link_name +[`link_ordinal`]: items.extern.attributes.link_ordinal [`unsafe` context]: ../unsafe-keyword.md [`verbatim` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-verbatim [`whole-archive` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-whole-archive @@ -467,4 +487,3 @@ Attributes on extern function parameters follow the same rules and restrictions [unwind-behavior]: functions.md#unwinding [value namespace]: ../names/namespaces.md [win32 api]: https://learn.microsoft.com/en-us/windows/win32/api/ -[`link_ordinal`]: items.extern.attributes.link_ordinal From 5df1b652474550a07bae2c4294e5155ccc734eb8 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 22 Sep 2025 13:03:08 -0700 Subject: [PATCH 4/4] Minor update of `link_ordinal` More closely align with the template, and some minor word tweaks. --- src/items/external-blocks.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 8243ca510e..4d5a5bf69a 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -420,6 +420,7 @@ Only the last use of `link_name` on an item has effect. r[items.extern.attributes.link_name.link_ordinal] The `link_name` attribute may not be used with the [`link_ordinal`] attribute. + r[items.extern.attributes.link_ordinal] ### The `link_ordinal` attribute @@ -452,10 +453,10 @@ r[items.extern.attributes.link_ordinal.max] The ordinal must be less than or equal to [`u16::MAX`]. r[items.extern.attributes.link_ordinal.allowed-positions] -The `link_ordinal` attribute may be specified on a function or static in an `extern` block. +The `link_ordinal` attribute may only be applied to a function or static in an `extern` block. r[items.extern.attributes.link_ordinal.duplicates] -The `link_ordinal` attribute may only be specified once on an item. +The `link_ordinal` attribute may be used only once on an item. r[items.extern.attributes.link_ordinal.allowed-kinds] The `link_ordinal` attribute may only be used with the [`raw-dylib` linking kind][items.extern.attributes.link.raw-dylib].