Guideline for `&Header` situations (treatment of pseudo-dynamically sized structs)

[kpreid]

From #428 (comment) and DCL38; posted on request by @felix91gr.

Background: C supports “flexible array members”, which indicate that a struct has an unknown number of array elements as its last field:

struct FlexStruct {
  int fixed_data;
  int flexible_data[];
};

In this case, the C programmer is obligated to write a program that keeps track, in whatever way it sees fit, of what the “actual” length of the array member is (commonly via storing the length in another field). Rust has “custom dynamically sized types (DSTs)” which are superficially similar and can be used for similar purposes,

struct DstStruct {
    fixed_data: i32,
    flexible_data: [i32],
}

but they are significantly different in that if you create any kind of pointer to DstStruct, it is mandatory that the size of the trailing slice field flexible_data is known, and stored as part of the pointer value (a “fat pointer” or “wide pointer”). Therefore, Rust DSTs cannot currently be used in all of the situations that C FAMs can. Programmers who are porting a C program to Rust, or who are writing FFI bindings to C code, may, therefore, be tempted to solve the problem by declaring a Rust struct without the dynamic size being known to the compiler:

#[repr(C)]
struct FauxDstStruct {
    fixed_data: i32,
    flexible_data: [i32; 0],
}

It is possible to use this struct (whose nominal size is the size of the fixed fields plus padding) in some cases. However, there is one key thing that is still an unresolved issue in Rust semantics: if you create a reference of type &FauxDstStruct or &mut FauxDstStruct, is it permissible to read or write any bytes of the flexible_data? Currently, no such permission has been granted, and some models of Rust semantics reject it as UB. Therefore, code intended to be correct and to be compiled with current and future Rust compilers must, today, avoid doing this.

Therefore, for the particular audience of experienced C programmers introducing Rust into their development, it may be worth having a guideline recommending that, in the matter of unsafely creating, or accessing through FFI, a variable-length structure in Rust, one of the following techniques must be employed:

1. Use a Rust dynamically sized struct, with the correct length. (This requires that the length not change and that wide pointers are suitable for the application.)
2. Or, refrain from referring to the struct using Rust reference types; use raw pointers or user-defined wrappers around raw pointers. Raw pointer types impose no assumptions about how much memory following their address is valid to access.
3. Or, use “extern types” (types which have unknown, rather than dynamically known, size). This is an unstable feature and thus may reasonably be considered unacceptable to use, but the “sized hierarchy” work currently in progress will hopefully lead to stable extern types in the near future.

Following these rules will avoid the creation of programs which might be determined to have UB by Rust’s future more-nailed-down semantics (or might even have UB today).

(Note that none of these considerations are relevant if unsafe code is not used. Without unsafe code, it is not possible to perform the possibly invalid access, though custom DSTs become far more difficult to create.)

[felix91gr]

2. Raw pointer types impose no assumptions about how much memory following their address is valid to access.

Question: are raw pointers not constrained (in terms of safety) to only do pointer arithmetic within their allocation? I ask because I believe that this would then mean that they do "impose an assumption", in the sense that they assume they are being used to read / write memory and compute pointers only within the stride of that allocation. Is that right?

[riking]

Yes, they are constrained to only do inbounds pointer arithmetic within their allocation, but the type of the pointer (and the dynamic size metadata in the pointer) has no obligation to have any structured relation to the type and size of the allocation.

Inbounds pointer arithmetic methods are .add(), .offset(), .sub(), etc. The .wrapping_add(), .wrapping_offset(), etc methods do not require that the result stays inbounds.

EDIT: If the pointer is a *const dyn SomeTrait, there is an obligation on the metadata: it must point to a valid vtable for SomeTrait at all times.

[kpreid]

are raw pointers not constrained (in terms of safety) to only do pointer arithmetic within their allocation?

Several points:

• First of all, to be precise, Rust has two sets of raw pointer arithmetic operations; the unsafe ones, and the “wrapping_*” ones. The wrapping_* functions are irrelevant here because they are allowed to go out of bounds (they defer all possible UB from when the pointer is computed to when it is dereferenced).

• The unsafe pointer arithmetic functions, such as add(), require that the raw pointer stay within its allocation. They do not require the raw pointer stay within its provenance. Provenance (which is what determines what you’re allowed to read or write) is always over some subset of the allocation.

• Broadly, the thing at issue here is whether operations that produce a pointer (whether reference or raw pointer) shrink the provenance or not — does making an &[mut] FauxDstStruct reference, by use of the borrow operator or other means, and passing it around, produce a reference which has provenance only to size_of::<FauxDstStruct>() bytes, rather than some prior larger provenance? But for raw pointers, this question has already been answered in the negative — the larger provenance is preserved.

Here is a quick demo program to play with (some elements may be dubious, and there are lots of plausible variations):

#[derive(Debug)]
#[repr(C)]
struct Foo {
    a: Bar,
    b: i32,
}

#[derive(Debug)]
#[repr(C)]
struct Bar {
    c: i32,
}

// roundabout implementation of `&mut foo.a` just to be clear
// this isn't *just* about using field access expressions
fn project(foo: &mut Foo) -> &mut Bar {
    unsafe { std::ptr::from_mut(foo).cast::<Bar>().as_mut().unwrap() }
}

/// Safety: `ptr` must point to a `Foo` and be valid for writes of `Foo`s
unsafe fn write_to_foo_around_bar(ptr: *mut Bar, value: i32) {
    unsafe {
        let ptr_to_b = ptr.add(1).cast::<i32>();
        ptr_to_b.write(value);
    }
}

fn main() {
    let mut foo = Foo { a: Bar { c: 1 }, b: 2 };
    
    unsafe {
        // this is OK — we have provenance for foo, and don't shrink it
        write_to_foo_around_bar((&raw mut foo).cast::<Bar>(), 200);
        // this is not OK, because involving `&mut Bar` shrunk provenance
        write_to_foo_around_bar(std::ptr::from_mut(project(&mut foo)), 400);
    }
    
    println!("{foo:?}");
}

If you run this program under Miri with default options, it will report UB on the second call to write_to_foo_around_bar, because under the Stacked Borrows model, the pointer it was given doesn’t have provenance for the b field. But if you remove the second call, you will see that the first call is completely fine, even though the Foo was written through a pointer of type *mut Bar.

This is why “use raw pointers and not references”, my second option listed in the original post, is one possible way to deal with a variable-size struct or an embedded header struct. However, it is still the most tricky-unsafe option, and so the other two (real Rust DSTs, and extern types) should be preferred if they are practical.