Skip to content

document that extern statics may be bigger than the declared size #2334

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
RalfJung wants to merge 3 commits into
base: master
Choose a base branch
from
Open

document that extern statics may be bigger than the declared size #2334

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6491ee0
document that extern statics may be bigger than the declared size
RalfJung Aug 22, 2026
ec8f4ef
add UB: invalid extern static
RalfJung Aug 24, 2026
199eef1
do not allow oversized raw-dylib statics
RalfJung Aug 26, 2026
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
4 changes: 4 additions & 0 deletions src/behavior-considered-undefined.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,10 @@ r[undefined.invalid]
r[undefined.asm]
* Incorrect use of inline assembly. For more details, refer to the [rules] to follow when writing code that uses inline assembly.

r[undefined.extern-static]
* Declaring an `extern static` with some size/alignment/mutability, when the actual symbol this resolves to is smaller / less aligned / less mutable.

@RalfJung RalfJung Aug 24, 2026 •
edited by rustbot
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new kind of UB is kind of remarkable in that it does not require any code to trigger. But I don't see an alternative...

View changes since the review

For `extern static` with `raw-dylib` linkage, the actual symbol must have *exactly* the declared size.

r[undefined.runtime]
* Violating assumptions of the Rust runtime. Most assumptions of the Rust runtime are currently not explicitly documented.
* For assumptions specifically related to unwinding, see the [panic documentation][unwinding-ffi].
Expand Down
8 changes: 8 additions & 0 deletions src/items/external-blocks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,10 @@ Extern statics can be either immutable or mutable just like [statics] outside of
r[items.extern.static.read-only]
An immutable static *must* be initialized before any Rust code is executed. It is not enough for the static to be initialized before Rust code reads from it. Once Rust code runs, mutating an immutable static (from inside or outside Rust) is UB, except if the mutation happens to bytes inside of an `UnsafeCell`.

r[items.extern.static.size]
The actual memory that the extern static resolves to [must have][extern-static-ub] *at least* the size and alignment of the type that it was declared with in the extern block.
If the actual memory is bigger, then it is permitted to access that extra memory.

@bjorn3 bjorn3 Aug 24, 2026 •
edited by rustbot
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For dynamic libraries that may be used by a PIE executable, the size given by the symbol must be exact given that the PIE executable will emit a copy relocation that copies a block with exactly the size the symbol had at link time to memory the executable image has reserved for this and redirect all accesses to the static to this copy. This way the executable can avoid GOT indirection, which is a slight perf win. And yes, this means adding elements to a static array in a dylib (or otherwise changing the size) is an ABI breaking change on Linux.

View changes since the review

@RalfJung RalfJung Aug 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uh... I understand like maybe half of those words. (Can I have some 🥧 please? :D )
"Copying" sounds wrong, statics are places and if you copy them, well, you have two copies so that can't be right?

But it sounds like you are saying linkme and inventory are unsound? IIRC they rely on extern statics that are bigger than declared, filled in by the linker.

@bjorn3 bjorn3 Aug 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Basically when linking the executable, space is reserved for each static referenced from a dylib inside the executable based on symbol size. Then at runtime the dynamic linker will copy the contents of the static in the dylib to the reserved space in the executable and redirect all references to this static to the version in the executable. So there are two copies in memory, but only the one inside the executable is observable by the user. The copy inside the dylib is unused and would be safe to unmap from memory after the dynamic linker has copied it.

linkme and inventory don't work across dylib boundaries anyway as they need the section they emit to be contiguous in memory. They would only see items defined inside the same dylib/executable as the one where the access code happened to be codegened.

@RalfJung RalfJung Aug 26, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

And what does that mean for crates like linkme/inventory?

@bjorn3 bjorn3 Aug 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

linkme and inventory only see items defined in the same dylib/executable as the access code is codegened. So if you depend on them to have a global view, you will get misbehavior.

@RalfJung RalfJung Aug 26, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For extern statics in (currently unstable for ELF) raw-dylib it is actually an issue as in that case the symbol size is retrieved from the type of the static.

That does sound like a problem. raw-dylib is also a complete mystery to me.^^ I don't understand why specifying the library I want to import from suddenly changes the rules regarding the size of the static...

So do we have to explicitly exclude raw-dylib from the new allowances in this section?

@bjorn3 bjorn3 Aug 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I said the linker needs to know the size somehow to determine the amount of memory to reserve in a PIE executable and to emit the right sized copy relocation. Either it gets this size from the upstream dylib or in the case of raw-dylib it gets it from the generated import library where rustc sets the size based on the type of the static.

@RalfJung RalfJung Aug 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah right, raw-dylib was the thing where you don.t have a .so file to look up the "actual source of truth" for these things. I guess that makes sense.

(currently unstable for ELF)

Why is ELF relevant here?

@bjorn3 bjorn3 Aug 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only ELF has copy relocations for PIE executables. The other object file formats don't implement this "optimization".

@RalfJung RalfJung Aug 26, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see.

Not sure if we should make our UB-rules format-dependent, though.


r[items.extern.abi]
## ABI

Expand Down Expand Up @@ -368,6 +372,9 @@ Specifying `kind = "dylib"` instructs the Rust compiler to link an import librar
r[items.extern.attributes.link.kind-raw-dylib.platform-specific]
`raw-dylib` is only supported on Windows. Using it when targeting other platforms will result in a compiler error.

r[items.extern.attributes.link.kind-raw-dylib.size]
Unlike regular external statics, a `raw-dylib` static is *not* allowed to be bigger than its declared size.

r[items.extern.attributes.link.import_name_type]
#### The `import_name_type` key

Expand Down Expand Up @@ -466,6 +473,7 @@ Attributes on extern function parameters follow the same rules and restrictions
[`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
[attributes]: ../attributes.md
[extern-static-ub]: ../behavior-considered-undefined.md#r-undefined.extern-static
[functions]: functions.md
[regular function parameters]: functions.md#attributes-on-function-parameters
[statics]: static-items.md
Expand Down
Loading