Skip to content

Update link_ordinal to use the attribute template #1897

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Update link_ordinal to use the attribute template #1897

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
39652fd
Unwrap link_ordinal
ehuss Jun 20, 2025
125b75d
Move example to example block
ehuss Jun 20, 2025
c362c89
Linkify "attribute"
ehuss Jun 20, 2025
cbc2edc
Update link_ordinal to use the attribute template
ehuss Jun 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 31 additions & 17 deletions src/items/external-blocks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -416,31 +416,44 @@ 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.

```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.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
Expand All @@ -461,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