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 5 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
5 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
41a5230
fix typo
RalfJung Sep 1, 2026
68f8440
tweak terminology, clarify
RalfJung Sep 2, 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 memory the extern static resolves to is smaller / less aligned / less mutable.
For `extern static` with `raw-dylib` linkage, the actual memory 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 within 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.

@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.

@CAD97 CAD97 Sep 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

There are two cases here, IIUC:

  • Rust is a dylib using the static. Access to the static goes through GOT lookup, independent of whether Rust is the definition site of the static or not. When linking to the dylib, the linker fixups must supply a memory region at least the declared size.
  • Rust is the binary using a static from a dylib. Rust supplies the memory region for the static matching the declared size. At dynamic linking time (before main), the dynamic linker writes the initialization value to the provided memory region for the static.

The memory region of the static always matches the declaration exactly if Rustc is the one allocating it; it's only when Rust is linking to an external memory region that it may potentially be larger. The case where Rust allocates the static and dynamic linking initializes it could be declared morally equivalent to life-before-main w.r.t. the abstract machine, and thus the initialization going out of bounds of the static is an out-of-bounds access unsoundness. Notably, if the Rust code declares a larger static that doesn't require the entire static value to be initialized, it's perfectly fine for the linker to copy initialize a smaller value in that memory region.

In conclusion, I think ELF copy relocation doesn't preclude allowing Rust extern static from linking to a memory region that ends up being larger than declared. But it is another weird case of where the wrong signature in an unsafe extern block can lead to UB even if the symbols go unused by Rust. Which isn't pretty, but it is the reality of today's compiler/linker plumbing.

@RalfJung RalfJung Sep 2, 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.

So... do you think the wording in the PR right now is accurate?
Note that this is about extern blocks. If you define a static in a Rust crate, compile that as a dylib, build a binary against that, and then load a different dylib into the binary, then there are all sorts of limitations that we have not even begun to document. That's not what I am trying to do here.

@bjorn3 bjorn3 Sep 2, 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.

Maybe change r[items.extern.attributes.link.kind-raw-dylib.size] to clarify that the size needs to match exactly, but that is effectively already implied when combined with r[items.extern.static.size], so fine either way.


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. The size needs to match exactly.

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