Skip to content

Commit ac50ab5

Browse files
committed
docs: don't claim struct layout is specified, but mention repr
1 parent 30bf73f commit ac50ab5

File tree

2 files changed

+29
-15
lines changed

2 files changed

+29
-15
lines changed

src/doc/guide-ffi.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -268,7 +268,7 @@ struct RustObject {
268268
// other members
269269
}
270270
271-
extern fn callback(target: *mut RustObject, a:i32) {
271+
extern "C" fn callback(target: *mut RustObject, a:i32) {
272272
println!("I'm called from C with value {0}", a);
273273
unsafe {
274274
// Update the value in RustObject with the value received from the callback
@@ -505,16 +505,16 @@ to define a block for all windows systems, not just x86 ones.
505505

506506
# Interoperability with foreign code
507507

508-
Rust guarantees that the layout of a `struct` is compatible with the platform's representation in C.
509-
A `#[packed]` attribute is available, which will lay out the struct members without padding.
510-
However, there are currently no guarantees about the layout of an `enum`.
508+
Rust guarantees that the layout of a `struct` is compatible with the platform's representation in C
509+
only if the `#[repr(C)]` attribute is applied to it. `#[repr(C, packed)]` can be used to lay out
510+
struct members without padding. `#[repr(C)]` can also be applied to an enum.
511511

512-
Rust's owned and managed boxes use non-nullable pointers as handles which point to the contained
512+
Rust's owned boxes (`Box<T>`) use non-nullable pointers as handles which point to the contained
513513
object. However, they should not be manually created because they are managed by internal
514-
allocators. References can safely be assumed to be non-nullable pointers directly to the
515-
type. However, breaking the borrow checking or mutability rules is not guaranteed to be safe, so
516-
prefer using raw pointers (`*`) if that's needed because the compiler can't make as many assumptions
517-
about them.
514+
allocators. References can safely be assumed to be non-nullable pointers directly to the type.
515+
However, breaking the borrow checking or mutability rules is not guaranteed to be safe, so prefer
516+
using raw pointers (`*`) if that's needed because the compiler can't make as many assumptions about
517+
them.
518518

519519
Vectors and strings share the same basic memory layout, and utilities are available in the `vec` and
520520
`str` modules for working with C APIs. However, strings are not terminated with `\0`. If you need a

src/doc/rust.md

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1221,6 +1221,9 @@ struct Cookie;
12211221
let c = [Cookie, Cookie, Cookie, Cookie];
12221222
~~~~
12231223

1224+
The precise memory layout of a structure is not specified. One can specify a
1225+
particular layout using the [`repr` attribute](
1226+
12241227
By using the `struct_inherit` feature gate, structures may use single inheritance. A Structure may only
12251228
inherit from a single other structure, called the _super-struct_. The inheriting structure (sub-struct)
12261229
acts as if all fields in the super-struct were present in the sub-struct. Fields declared in a sub-struct
@@ -1851,6 +1854,23 @@ interpreted:
18511854
- `linkage` - on a static, this specifies the [linkage
18521855
type](http://llvm.org/docs/LangRef.html#linkage-types).
18531856

1857+
On `enum`s:
1858+
1859+
- `repr` - on C-like enums, this sets the underlying type used for
1860+
representation. Takes one argument, which is the primitive
1861+
type this enum should be represented for, or `C`, which specifies that it
1862+
should be the default `enum` size of the C ABI for that platform. Note that
1863+
enum representation in C is undefined, and this may be incorrect when the C
1864+
code is compiled with certain flags.
1865+
1866+
On `struct`s:
1867+
1868+
- `repr` - specifies the representation to use for this struct. Takes a list
1869+
of options. The currently accepted ones are `C` and `packed`, which may be
1870+
combined. `C` will use a C ABI comptible struct layout, and `packed` will
1871+
remove any padding between fields (note that this is very fragile and may
1872+
break platforms which require aligned access).
1873+
18541874
### Miscellaneous attributes
18551875

18561876
- `link_section` - on statics and functions, this specifies the section of the
@@ -1860,12 +1880,6 @@ interpreted:
18601880
symbol for this item to its identifier.
18611881
- `packed` - on structs or enums, eliminate any padding that would be used to
18621882
align fields.
1863-
- `repr` - on C-like enums, this sets the underlying type used for
1864-
representation. Useful for FFI. Takes one argument, which is the primitive
1865-
type this enum should be represented for, or `C`, which specifies that it
1866-
should be the default `enum` size of the C ABI for that platform. Note that
1867-
enum representation in C is undefined, and this may be incorrect when the C
1868-
code is compiled with certain flags.
18691883
- `simd` - on certain tuple structs, derive the arithmetic operators, which
18701884
lower to the target's SIMD instructions, if any.
18711885
- `static_assert` - on statics whose type is `bool`, terminates compilation

0 commit comments

Comments
 (0)