From 5b07f7c95bfd683d14d44eee1af3d86eb57b0362 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:36:09 -0700 Subject: [PATCH 1/5] Unwrap link_ordinal --- src/items/external-blocks.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index c360189ba..d43cddafd 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -501,11 +501,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* 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. @@ -520,12 +516,10 @@ unsafe extern "stdcall" { ``` 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. +This attribute is only used with the `raw-dylib` linking kind. Using any other kind will result in a compiler error. r[items.extern.attributes.link_ordinal.exclusive] -Using this attribute with the `link_name` attribute will result in a -compiler error. +Using this attribute with the `link_name` attribute will result in a compiler error. r[items.extern.attributes.fn-parameters] ### Attributes on function parameters From 0df944bc4d4a4dbefcda1757e0076becda99c479 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:52:40 -0700 Subject: [PATCH 2/5] 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 d43cddafd..d9e460ea7 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -506,14 +506,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 9437ba8e3a8bdc7ca05544b3227f6a5c94779821 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:52:51 -0700 Subject: [PATCH 3/5] 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 d9e460ea7..2f19f0f08 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -501,7 +501,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 d4c24e3e0aafc70d334284b874d4367e0a71f934 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:55:00 -0700 Subject: [PATCH 4/5] 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 2f19f0f08..187748924 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -516,11 +516,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 @@ -535,6 +553,8 @@ restrictions as [regular function parameters]. [`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 @@ -545,4 +565,3 @@ restrictions as [regular function parameters]. [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 7429b4bff5aea17c326eda6f002a171daf236aec Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 22 Sep 2025 13:03:08 -0700 Subject: [PATCH 5/5] 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 187748924..4d62662e2 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -497,6 +497,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 @@ -529,10 +530,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].