rfcs/text/1399-repr-pack.md

4.2 KiB

Summary

Extend the existing #[repr] attribute on structs with a packed = "N" option to specify a custom packing for struct types.

Motivation

Many C/C++ compilers allow a packing to be specified for structs which effectively lowers the alignment for a struct and its fields (for example with MSVC there is #pragma pack(N)). Such packing is used extensively in certain C/C++ libraries (such as Windows API which uses it pervasively making writing Rust libraries such as winapi challenging).

At the moment the only way to work around the lack of a proper #[repr(packed = "N")] attribute is to use #[repr(packed)] and then manually fill in padding which is a burdensome task. Even then that isn't quite right because the overall alignment of the struct would end up as 1 even though it needs to be N (or the default if that is smaller than N), so this fills in a gap which is impossible to do in Rust at the moment.

Detailed design

The #[repr] attribute on structs will be extended to include a form such as:

#[repr(packed = "2")]
struct LessAligned(i16, i32);

This structure will have an alignment of 2 and a size of 6, as well as the second field having an offset of 2 instead of 4 from the base of the struct. This is in contrast to without the attribute where the structure would have an alignment of 4 and a size of 8, and the second field would have an offset of 4 from the base of the struct.

Syntactically, the repr meta list will be extended to accept a meta item name/value pair with the name "packed" and the value as a string which can be parsed as a u64. The restrictions on where this attribute can be placed along with the accepted values are:

  • Custom packing can only be specified on struct declarations for now. Specifying a different packing on perhaps enum or type definitions should be a backwards-compatible extension.
  • Packing values must be a power of two.

By specifying this attribute, the alignment of the struct would be the smaller of the specified packing and the default alignment of the struct. The alignments of each struct field for the purpose of positioning fields would also be the smaller of the specified packing and the alignment of the type of that field. If the specified packing is greater than or equal to the default alignment of the struct, then the alignment and layout of the struct should be unaffected.

When combined with #[repr(C)] the size alignment and layout of the struct should match the equivalent struct in C.

#[repr(packed)] and #[repr(packed = "1")] should have identical behavior.

Because this lowers the effective alignment of fields in the same way that #[repr(packed)] does (which caused issue #27060), while accessing a field should be safe, borrowing a field should be unsafe.

Specifying #[repr(packed)] and #[repr(packed = "N")] where N is not 1 should result in an error.

Specifying #[repr(packed = "A")] and #[repr(align = "B")] should still pack together fields with the packing specified, but then increase the overall alignment to the alignment specified. Depends on RFC #1358 landing.

Drawbacks

Alternatives

  • The alternative is not doing this and forcing people to continue using #[repr(packed)] with manual padding, although such structs would always have an alignment of 1 which is often wrong.
  • Alternatively a new attribute could be used such as #[pack].

Unresolved questions

  • The behavior specified here should match the behavior of MSVC at least. Does it match the behavior of other C/C++ compilers as well?
  • Should it still be safe to borrow fields whose alignment is less than or equal to the specified packing or should all field borrows be unsafe?