diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..b25c15b8 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +*~ diff --git a/reference/src/representation/unions.md b/reference/src/representation/unions.md new file mode 100644 index 00000000..44d343cd --- /dev/null +++ b/reference/src/representation/unions.md @@ -0,0 +1,36 @@ +# Representation of unions + +**Disclaimer:** This chapter represents the consensus from issue +[#13]. The statements in here are not (yet) "guaranteed" +not to change until an RFC ratifies them. + +[#13]: https://github.com/rust-rfcs/unsafe-code-guidelines/issues/13 + +The only degree of freedom the compiler has when computing the layout of a union +like + +```rust +union U { f1: T1, f2: T2 } +``` + +is to determine the offset of the fields. The layout of these fields themselves +is already entirely determined by their types, and since we intend to allow +creating references to fields (`&u.f1`), unions do not have any wiggle-room +there. + +### C-compatible layout ("repr C") + +For unions tagged `#[repr(C)]`, the compiler will apply the C layout scheme. Per +sections [6.5.8.5] and [6.7.2.1.16] of the C11 specification, this means that +the offset of every field is 0. Unsafe code can case a pointer to the union to +a field type to obtain a pointer to any field, and vice versa. + +[6.5.8.5]: http://port70.net/~nsz/c/c11/n1570.html#6.5.8p5 +[6.7.2.1.16]: http://port70.net/~nsz/c/c11/n1570.html#6.7.2.1p16 + +### Default layout ("repr rust") + +**The default layout of unions is not specified.** As of this writing, we want +to keep the option of using non-zero offsets open for the future; whether this +is useful depends on what exactly the compiler-assumed invariants about union +contents are.