Distinguish `repr(C)` ZSTs from others in ABI compatibility rules by Jules-Bertholet · Pull Request #157973 · rust-lang/rust

Jules-Bertholet · 2026-06-16T14:10:10Z

(Split out from compiler implementation in #156112)

Some C ABIs pass and return ZSTs by pointer. But () should never be returned by pointer, as it must match void. To account for this, we have to weaken the present guarantee of "any two types with size 0 and alignment 1 are ABI-compatible" to exclude repr(C).

t-lang nomination summary comment

Fixes rust-lang/unsafe-code-guidelines#552; see also #78586, #155299.
Also related to #155984.

@rustbot label T-lang A-ABI needs-fcp

rustbot · 2026-06-16T14:10:18Z

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: libs
libs expanded to 11 candidates
Random selection from 6 candidates

Jules-Bertholet · 2026-06-19T19:01:03Z

+///   - Alignment 1
+///   - Not `repr(C)`
+///   - Not a `repr(transparent)` wrapper around a type that fails to satisfy these conditions
+///   - Not an array whose element type fails to satisfy these conditions


We exempt arrays for 2 reasons:

A future version of C, or some other language we would like to do FFI with, might allow passing arrays to functions directly by value, in a way that would conflict with these guarantees

It would be nice to also use "trivial ABI" in the specification of repr(C), and we need this clause for that. See discussion at repr(ordered_fields) rfcs#3845 (comment)

We could also simplify this clause by saying merely:

Suggested change

/// - Not an array whose element type fails to satisfy these conditions

/// - Not an array

The downside would be a larger breaking change.

Note that repr(transparent) will need to be adjusted to account for this change (by rejecting non-trivial arrays as "additional" fields).

View changes since the review

I'm fine with saying that "all arrays with trivial-ABI element type have trivial ABI".

However, even that less-breaking version breaks ghost again, right? Similar to dtolnay/ghost#41. ghost uses a zero-length array of *const T, which definitely does not have trivial ABI. I don't know why they do that...

EDIT: Ah, ghost is saved by having a repr(Rust) type around the array, under the rules discussed here.

Mark-Simulacrum

Probably mostly an opsem question in my eyes, at least to figure out the right shape. I see there's already been some discussion but I think nailing the language is probably better delegated too.

r? opsem

View changes since this review

Mark-Simulacrum · 2026-06-21T18:57:39Z

Some C ABIs pass and return ZSTs by pointer. But () should never be returned by pointer, as it must match void. To account for this, we have to weaken the present guarantee of "any two types with size 0 and alignment 1 are ABI-compatible" to exclude repr(C).

I think the implication here is that () is repr(C)? Am I reading that right? Where do we make that guarantee? Or is the thinking that the language here would make () and #[repr(C)] struct Foo; not ABI compatible?

One callout is that ZSTs aren't (I think?) standardized -- C and C++ without extensions both require types to be non-ZST if I remember right (e.g., see https://stackoverflow.com/a/2632075). Maybe that has changed since then though?

It seems like at minimum, it would be nice to avoid weakening this guarantee for Rust ABI even if we do so for C ABIs as a result of the weird platforms.

Or is the thinking that the language here would make () and #[repr(C)] struct Foo; not ABI compatible?

Yes, this.

One callout is that ZSTs aren't (I think?) standardized

Correct.

RalfJung · 2026-07-02T14:10:14Z

+/// - Any two types fulfilling all the following conditions are ABI-compatible;
+///   such types are said to have "trivial ABI":


Suggested change

/// - Any two types fulfilling all the following conditions are ABI-compatible;

/// such types are said to have "trivial ABI":

/// - Any two types with "trivial ABI" are ABI-compatible.

/// A type has trivial ABI if is satisfies all of the following:

View changes since the review

RalfJung · 2026-07-02T14:26:24Z

@rust-lang/opsem @rust-lang/lang what do you think? I think we do have to take back a bit of what we promised here, since we did promise too much. The current docs say:

Any two types with size 0 and alignment 1 are ABI-compatible.

This is plain wrong for extern "C" on Windows where the following types do not have the same ABI when used in return position:

// This is returned by-ptr.
#[repr(C)]
struct T1 {}

// This matches a C function returning `void`.
type T2 = ();

T1 is passed and returned by-ptr by MSVC so we have to do the same. But () means void so it cannot be returned by-ptr.
In argument position they do have the same ABI, but the way we achieve this is silly: we pass a pointer for () arguments.

So the proposal is to restrict the above rule as follows:

Any two types fulfilling all the following conditions are ABI-compatible; such types are said to have "trivial ABI":
- It has size 0.
- It has alignment 1.
- One of the following apply:
  - It is a repr(Rust) (implicitly or explicitly, possibly with additional flags such as packed) struct, enum, union (regardless of its fields).
  - It is a tuple (regardless of its fields, and including ().
  - It is a repr(transparent) struct, enum, or union, and all fields have trivial ABI.
  - It is an array, and its element type has trivial ABI. (This requirement applies even to arrays of length 0.)
  - It is the never type !.
  - It is a function item type or closure type.

Under the old rules, we effectively said "All 1-ZST have trivial ABI". Now we have some further restrictions. I think the only types that used to have trivial ABI but don't any more are repr(C) 1-ZST and zero-length arrays of non-zero-sized types such as [u8; 0], as well as repr(transparent) wrappers around such types.

Note that we also have to adjust the logic for repr(transparent) to ensure that all the types it ignores have "trivial ABI" according to these rules. So there's two breaking changes here:

Code that relied on the ABI compatibility we are taking away now has UB.
Code that relied on repr(transparent) ignoring a 1-ZST that we no longer consider to be "trivial" will stop compiling.

I cratered the 2nd part and found 0 regressions.

I don't know how to measure the fallout from the 1st breakage. We should implement this in Miri, but even that will just give us a very incomplete partial picture.

That said, given that the current docs are wrong, we have to do something. The only actually open question (in my eyes) is how bespoke we want the rules to be with the aim of breaking less code.

We could have different ABI compatibility rules for the "Rust" ABI and the "C" ABI, and say that all 1-ZST have "trivial Rust ABI". This would theoretically reduce the amount of case 1 breakage (but we don't know anything about that breakage so it's unclear if there even exists code that would be helped by this). Currently our ABI compatibility notion is independent of the ABI used by the function, so this adds non-trivial extra complexity on the docs side. I don't think we should do this.
The rules in this PR say that all repr(Rust) 1-ZST have trivial ABI, without recursing further. This means that adding repr(transparent) to a type can make it lose its "trivial ABI" property! The way to intuitively understand this is that by adding repr(transparent) you are forcing the ABI to be compatible with at least one field, and if that field has an ABI that's determined by the C platform then we can't say that it has trivial ABI. The reason we do this is two-fold: this means more types have "trivial ABI", so we reduce the amount of type 1 breakage. And it means we can keep a pattern used by the ghost crate working (specifically, this allows us to consider a ghost-declared phantom type as being "trivial" for repr(transparent)).

Co-authored-by: Brian Smith <brian@briansmith.org> Co-authored-by: Ralf Jung <post@ralfj.de>

Co-authored-by: Ralf Jung <post@ralfj.de>

RalfJung · 2026-07-15T06:41:05Z

Does the Reference have any discussion of ABI compatibility currently? Hard to make a PR with a diff to something that's not even in the Reference yet.

Darksonn · 2026-07-15T07:00:43Z

+///     - It is an array, and its element type has trivial ABI. (This requirement applies even to arrays of length 0.)
+///     - It is [the never type `!`][prim_never].
+///     - It is a function item type or closure type.


I think this change is reasonable. We have to change these rules because they're just wrong and this is unfixable. The rules as stated seem like a reasonable way to fix it.

My main question would be: Why include arrays? I get a bit worried about that one because array arguments have weird properties in C. We don't want to run into another case in the future where Rust cannot represent certain kinds of C ABIs involving arrays.

View changes since the review

See discussion thread at #157973 (comment). The "and its element type has trivial ABI" requirement should exclude array types with C equivalents.

Hrm, I guess you are right that the element type having a trivial ABI requirement is probably sufficient.

RalfJung · 2026-07-15T15:25:18Z

Let's just ask opsem officially. :)
@rfcbot merge opsem

traviscross · 2026-07-15T19:27:06Z

Let's poll both in parallel.

@rfcbot cancel

rust-rfcbot · 2026-07-15T19:27:08Z

@traviscross proposal cancelled.

traviscross · 2026-07-15T19:27:22Z

@rfcbot fcp merge lang,opsem

rust-rfcbot · 2026-07-15T19:27:34Z

CAD97 · 2026-07-15T21:33:02Z

I still personally think that, given a time machine, using anything in #[repr(C)]/extern "C" that doesn't have a corresponding equivalent in the C standard should've been an error. In such a world, system would be the identifier for getting "C with the target system extensions" semantics.

That said, I do recognize practicality. Lacking a time machine, I agree that this is the correct thing to do for Rust in practice.

@rustbot reviewed

Jules-Bertholet · 2026-07-15T21:38:33Z

Does the Reference have any discussion of ABI compatibility currently?

The Reference actually delegates explicitly to these stdlib docs: https://doc.rust-lang.org/reference/type-layout.html#r-layout.guarantees

After this PR is merged, we'll need to do the follow-up work of adjusting repr(transparent), and the relevant section of the Reference will need to be modified at that point. We're not there yet, though.

saethlin · 2026-07-17T03:53:40Z

The current rules say that all repr(Rust) 1-ZST have trivial ABI, without recursing further.

Isn't this PR introducing the concept of "trivial ABI"? It's worded like it does. I would like to read the rendered documentation for this file on the website but I can't find what page primitive_docs.rs is rendered as. It's definitely not std::primitive which is the only promising search result.

Jules-Bertholet · 2026-07-17T04:17:01Z

I can't find what page primitive_docs.rs is rendered as.

As many pages, but the relevant one for this PR is https://doc.rust-lang.org/core/primitive.fn.html#abi-compatibility

I think that by "current rules", Ralf was referring to the current state of this PR.

RalfJung · 2026-07-17T06:32:55Z

I think that by "current rules", Ralf was referring to the current state of this PR.

Yes, sorry for the confusion. The PR was changed a bit in the beginning. I have clarified my comment.

RalfJung · 2026-07-17T12:12:54Z

Is it correct that the only 1-ZST that don't have trivial ABI under this are things like [u8; 0] and repr(C) structs, and repr(transparent) wrappers around such types?

(I think our rules should be stated the way they are, positively, but for understanding what this changes compared to the status quo it is useful to also think of what the exceptions are.)

Darksonn · 2026-07-18T10:05:56Z

I can't think of anything else.

workingjubilee · 2026-07-20T00:01:41Z

+///   - It has size 0.
+///   - It has alignment 1.
+///   - One of the following apply:
+///     - It is a `repr(Rust)` (implicitly or explicitly, possibly with additional flags such as `packed`) `struct`, `enum`, `union` (regardless of its fields).


I tried to read this while asking myself why repr(packed) doesn't matter here. I know, and you know, but does every reader know? Why is it just an "additional flag"? I am inclined to think this is currently confusingly worded.

To start, it uses the term "flag", which feels a bit out-of-left field, like you're thinking about how the compiler reduces this to bitflags, but elsewhere on this page the only use of "flags" is in reference to compiler flags. We instead should talk, here, about the source syntax alone, attributes.

I think something like this would be a wording that makes it clearer that some attributes do conflict with repr(Rust), and some do not, the latter of which you referred to as "additional". If this seems like a bit much then maybe the text should just say "implicitly or explicitly" and move on, possibly with a reference to an explanation elsewhere or pushing the warning text into a later example.

Suggested change

/// - It is a `repr(Rust)` (implicitly or explicitly, possibly with additional flags such as `packed`) `struct`, `enum`, `union` (regardless of its fields).

/// - It is a `repr(Rust)` `struct`, `enum`, or `union`, regardless of its fields. This includes when a type is implicitly assigned `repr(Rust)` because no explicit `repr` attribute would conflict, such as when `repr(packed)` is treated as `repr(Rust, packed)`, as opposed to `repr(C, packed)`.

View changes since the review

Also, the parentheses are unnecessary if we use a sentence structure that doesn't need them.

To start, it uses the term "flag", which feels a bit out-of-left field

Good point. Changed to "modifier", which is what the Reference uses.

Also, the parentheses are unnecessary if we use a sentence structure that doesn't need them.

I use parentheses to enclose clarifications that don't change the meaning (as opposed to normative statements). That's a valuable distinction, and parentheses are the punctuation best suited to express it.

Hmm. I honestly don't really assign any such extremely specific intent to parentheses because they are used to provide "additional explanation" in various contexts and whether or not that is meaning-changing is ambiguous.

Footnotes are something that one might imagine to be non-normative and merely clarifying, yes? But the entire C programming ecosystem rests on a footnote's "clarification" being treated as normative.

I will give it another read to see if it makes sense with that, though.

So, regarding parens: Mostly, it feels confusing to read something that is constantly interrupting itself. I actually prefer the next line because it finishes a thought in one sentence, then has another sentence in parentheses. While I felt that made the parentheses slightly redundant, if you think they're a useful stylistic qualifier between normative/clarifying, then that's fine. But if you can find a variant of this line that reads more like that one, it would be appreciated.

workingjubilee · 2026-07-20T00:09:31Z

+///   - It has alignment 1.
+///   - One of the following apply:
+///     - It is a `repr(Rust)` (implicitly or explicitly, possibly with additional flags such as `packed`) `struct`, `enum`, `union` (regardless of its fields).
+///     - It is a [tuple][prim_tuple] (regardless of its fields, and including [`()`][prim_unit]).


Less parens, please.

Suggested change

/// - It is a [tuple][prim_tuple] (regardless of its fields, and including [`()`][prim_unit]).

/// - It is a [tuple][prim_tuple], including [`()`][prim_unit], regardless of its fields.

View changes since the review

Rephrasing without the specific note about parens: I think reminding people that () is technically considered a tuple here is more important, thus should come first.

I initially considered suggesting just removing every "regardless of..." case and letting the absence of qualifier speak for itself. There are good reasons to not, however.

riking · 2026-07-20T07:51:23Z

 ///     `packed` representation modifiers.
 ///   - The enum `E` has exactly two variants.
 ///   - One variant has exactly one field, of type `T`.
 ///   - All fields of the other variant are zero-sized with 1-byte alignment.


Here as well, "have trivial ABI" instead of size/align

View changes since the review

In don't think so. This is about a repr(Rust) enum, we fully make the rules there, and we can totally say that [u8; 0] will be ignored without having to worry about C compatibility.

Co-authored-by: Ralf Jung <post@ralfj.de>

rustbot · 2026-07-20T12:04:17Z

⚠️ Warning ⚠️

This PR is based on an upstream commit that is older than 28 days.

It's recommended to update your branch according to the rustc-dev-guide.

Distinguish repr(C) ZSTs from others in ABI compatibility rules

31d03e7

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jun 16, 2026

rustbot assigned Mark-Simulacrum Jun 16, 2026

rustbot added A-ABI Area: Concerning the application binary interface (ABI) needs-fcp This change is insta-stable, or significant enough to need a team FCP to proceed. T-lang Relevant to the language team labels Jun 16, 2026

Jules-Bertholet mentioned this pull request Jun 16, 2026

Distinguish repr(C) ZSTs from others in ABI computation #156112

Open

Make most arrays non-trivial

34de188

Jules-Bertholet commented Jun 19, 2026

View reviewed changes

Jules-Bertholet mentioned this pull request Jun 19, 2026

repr(ordered_fields) rust-lang/rfcs#3845

Open

Mark-Simulacrum reviewed Jun 21, 2026

View reviewed changes

rustbot added the T-opsem Relevant to the opsem team label Jun 21, 2026

rustbot assigned CAD97 and unassigned Mark-Simulacrum Jun 21, 2026

Jules-Bertholet mentioned this pull request Jun 22, 2026

"Any two types with size 0 and alignment 1 are ABI-compatible" vs the Windows ABI rust-lang/unsafe-code-guidelines#552

Open

RalfJung reviewed Jul 2, 2026

View reviewed changes

Comment thread library/core/src/primitive_docs.rs Outdated

RalfJung reviewed Jul 2, 2026

View reviewed changes

Comment thread library/core/src/primitive_docs.rs Outdated

RalfJung reviewed Jul 2, 2026

View reviewed changes

RalfJung added the I-lang-nominated Nominated for discussion during a lang team meeting. label Jul 2, 2026

Improve wording

41e5d13

This was referenced Jul 2, 2026

Don't use repr(C) dtolnay/ghost#42

Merged

repr(transparent): never consider arrays trivial for the ABI #156114

Closed

Future-proofing

a01211b

RalfJung mentioned this pull request Jul 2, 2026

repr(transparent): don't consider most length-0 arrays trivial #155984

Draft

Improve wording

a9bed71

Co-authored-by: Brian Smith <brian@briansmith.org> Co-authored-by: Ralf Jung <post@ralfj.de>

RalfJung reviewed Jul 4, 2026

View reviewed changes

Comment thread library/core/src/primitive_docs.rs Outdated

Avoid negation

3e86bb0

Co-authored-by: Ralf Jung <post@ralfj.de>

traviscross added the P-lang-drag-2 Lang team prioritization drag level 2.https://rust-lang.zulipchat.com/#narrow/channel/410516-t-lang. label Jul 14, 2026

Darksonn reviewed Jul 15, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

rust-rfcbot removed proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. labels Jul 15, 2026

rust-rfcbot added proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. labels Jul 15, 2026

traviscross added P-lang-drag-1 Lang team prioritization drag level 1. https://rust-lang.zulipchat.com/#narrow/channel/410516-t-lang and removed P-lang-drag-2 Lang team prioritization drag level 2.https://rust-lang.zulipchat.com/#narrow/channel/410516-t-lang. labels Jul 15, 2026

workingjubilee reviewed Jul 20, 2026

View reviewed changes

"flags" -> "modifiers"

fd2f2de

riking reviewed Jul 20, 2026

View reviewed changes

Add clarifying note about all-trivial repr(transparent)

22d1733

Co-authored-by: Ralf Jung <post@ralfj.de>

	/// - Not an array whose element type fails to satisfy these conditions
	/// - Not an array

		/// - Any two types fulfilling all the following conditions are ABI-compatible;
		/// such types are said to have "trivial ABI":

	/// - It is a `repr(Rust)` (implicitly or explicitly, possibly with additional flags such as `packed`) `struct`, `enum`, `union` (regardless of its fields).
	/// - It is a `repr(Rust)` `struct`, `enum`, or `union`, regardless of its fields. This includes when a type is implicitly assigned `repr(Rust)` because no explicit `repr` attribute would conflict, such as when `repr(packed)` is treated as `repr(Rust, packed)`, as opposed to `repr(C, packed)`.

	/// - It is a [tuple][prim_tuple] (regardless of its fields, and including [`()`][prim_unit]).
	/// - It is a [tuple][prim_tuple], including [`()`][prim_unit], regardless of its fields.

Uh oh!

Uh oh!

Conversation

Jules-Bertholet commented Jun 16, 2026 • edited by RalfJung Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jun 16, 2026

Uh oh!

Jules-Bertholet Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mark-Simulacrum left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mark-Simulacrum Jun 21, 2026

Choose a reason for hiding this comment

Uh oh!

Jules-Bertholet Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

RalfJung Jul 2, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

RalfJung commented Jul 15, 2026

Uh oh!

Darksonn Jul 15, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jules-Bertholet Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

Darksonn Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

RalfJung commented Jul 15, 2026

Uh oh!

This comment was marked as outdated.

traviscross commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rust-rfcbot commented Jul 15, 2026

Uh oh!

traviscross commented Jul 15, 2026

Uh oh!

rust-rfcbot commented Jul 15, 2026 • edited by CAD97 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CAD97 commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Jules-Bertholet commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

saethlin commented Jul 17, 2026

Uh oh!

Jules-Bertholet commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RalfJung commented Jul 17, 2026

Uh oh!

RalfJung commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Darksonn commented Jul 18, 2026

Uh oh!

Jules-Bertholet commented Jun 16, 2026 •

edited by RalfJung

Loading

Jules-Bertholet Jun 19, 2026 •

edited

Loading

RalfJung Jul 2, 2026 •

edited

Loading

Mark-Simulacrum left a comment •

edited by rustbot

Loading

Jules-Bertholet Jun 21, 2026 •

edited

Loading

RalfJung Jul 2, 2026 •

edited by rustbot

Loading

RalfJung commented Jul 2, 2026 •

edited

Loading

Darksonn Jul 15, 2026 •

edited by rustbot

Loading

traviscross commented Jul 15, 2026 •

edited

Loading

rust-rfcbot commented Jul 15, 2026 •

edited by CAD97

Loading

CAD97 commented Jul 15, 2026 •

edited

Loading

Jules-Bertholet commented Jul 15, 2026 •

edited

Loading

Jules-Bertholet commented Jul 17, 2026 •

edited

Loading

RalfJung commented Jul 17, 2026 •

edited

Loading

workingjubilee Jul 20, 2026 •

edited by rustbot

Loading

Jules-Bertholet Jul 20, 2026 •

edited

Loading

workingjubilee Jul 20, 2026 •

edited by rustbot

Loading

workingjubilee Jul 20, 2026 •

edited

Loading

riking Jul 20, 2026 •

edited by rustbot

Loading

RalfJung Jul 20, 2026 •

edited

Loading