From 39652fddc308a41e676855662fd29c6dd963407c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:36:09 -0700 Subject: [PATCH 1/4] 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 b60cb4505..c340c9788 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -416,11 +416,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. @@ -435,12 +431,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 125b75decf5c9f00eeff9255ecc1fe76104f92f9 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:52:40 -0700 Subject: [PATCH 2/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 c340c9788..483b339c2 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -421,14 +421,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 c362c899ced9d78136453bdbb3fc092e47202e35 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:52:51 -0700 Subject: [PATCH 3/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 483b339c2..f34b214b4 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -416,7 +416,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 cbc2edcd1f693b0201c4e5f19c696583721ae991 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Jun 2025 16:55:00 -0700 Subject: [PATCH 4/4] Update link_ordinal to use the attribute template --- src/items/external-blocks.md | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index f34b214b4..08dbc600b 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -431,11 +431,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 @@ -456,3 +474,4 @@ restrictions as [regular function parameters]. [statics]: static-items.md [unwind-behavior]: functions.md#unwinding [value namespace]: ../names/namespaces.md +[`link_name`]: items.extern.attributes.link_name