Document how Rust array/slice types are translated for extern "C" functions.

[briansmith]

Currently I write:

extern {
    fn X25519(out_shared_key: *mut u8/*[32]*/, private_key: *const u8/*[32]*/,
              peers_public_value: *const u8/*[32]*/) -> libc::c_int;
}

I would like to write:

extern {
    fn X25519(out_shared_key: &mut [u8;32], private_key: &[u8;32],
              peers_public_value: &[u8;32]) -> libc::c_int;
}

The C declaration is:

int X25519(uint8_t out_shared_key[32], const uint8_t private_key[32],
           const uint8_t peers_public_value[32]);

which is equivalent to:

int X25519(uint8_t *out_shared_key, const uint8_t *private_key,
           const uint8_t *peers_public_value);

The second form of the Rust ffi declaration is safer because it makes it clear that the function doesn't accept NULL pointers and it also makes it clear how long the input arrays are expected to be. However, the Rust reference doesn't document how it translates a reference to a slice or array to a C type, so using the second form is undefined behavior. I would like the Rust Reference to be amended to make it clear that it will call translate references to arrays/slices by passing the result of as_ptr/as_mut_ptr to the C function.

[Aatch]

Note that this may require an RFC actually specifying this and related information.

[briansmith]

Also, more generally, it should be documented that a reference will be translated to a pointer, so that extern "C" functions can use references instead of pointers to denote the non-acceptance of NULLs.

[retep998]

Pointers to slices (aka &[T]) are fat and thus can't be used for FFI.

Pointers to fixed size arrays (aka &[T; N]) are thin and thus I imagine they should be perfectly okay even if it isn't spelled out in the documentation.

[steveklabnik]

So, following up: what needs to be done here, exactly, and where should it go? FFI should say that fat pointers aren't usable?

[steveklabnik]

I am going to give this one a close. I'm not going to do a whole ton of work on the existing FFI docs, focusing on the new one instead, and talking about fat vs thin pointers wrt FFI is a big thing.

[briansmith]

I am going to give this one a close. I'm not going to do a whole ton of work on the existing FFI docs, focusing on the new one instead, and talking about fat vs thin pointers wrt FFI is a big thing.

I don't understand why we're so eager to close bugs without fixing them. It isn't a matter of "existing FFI docs" vs "new one" but the fact that it is unspecified what happens. Also, it isn't just a documentation bug because the compiler should be aligned with what ever is decided. In particular, is what the Rust compiler currently does right or wrong?

[arielb1]

Casting a fat pointer to a thin pointer returns the fat pointer's base. If the pointer was unsized from a thin pointer, that is the original thin pointer. If the pointer was created by from_raw_parts (e.g. from a Vec), it is the base parameter to that method. I was quite sure that this is sufficiently documented.

You are only supposed to use FFI-safe types for FFI. Fat pointers are not FFI-safe types, therefore their representation should not matter. Thin pointers are stored in the obvious way, but I think that is documented.

Slices/arrays are stored in memory in the obvious way (Rust requires that align | size so there is 1 such way). This is documented in the Rustonomicon:

However with the exception of arrays (which are densely packed and in-order), the layout of data is not by default specified in Rust.

[briansmith]

You are only supposed to use FFI-safe types for FFI. Fat pointers are not FFI-safe types, therefore their representation should not matter.

1. Where is the set of FFI-safe types documented?
2. Assuming slices aren't FFI-safe types, why does the compiler let us pass non-FFI-safe types to foreign functions?
3. Assuming slices aren't FFI-safe types, why not?

[bluss]

There's a lint for this, at least when declaring extern functions -- example on playpen

<anon>:4:26: 4:30 warning: found Rust slice type in foreign module, consider using a raw pointer instead, #[warn(improper_ctypes)] on by default
<anon>:4     fn other_find(text: &[u8], x: u8) -> Option<usize>;

[arielb1]

The representation of types is documented at https://doc.rust-lang.org/nightly/nomicon/data.html. In general, the rule is that types are FFI-safe ~ have a defined representation only if we say that they are that. Reading it again, it seems that we never say that primitives and thin pointers are FFI-safe - cc #31227 !

The currently most significant reason that fat pointers are not FFI safe is because we sometimes pass fat pointers as 2 arguments to a function instead of as a single 2-word argument.
For example, it may be possible to write memcpy as

extern {
    fn memcpy(dst: *mut u8, src: &[u8]); // THIS DOES NOT HAVE TO WORK!
}

[bluss]

I don't think the array part of this issue was answered. &mut [u8; 32] should be ffi safe, what more can we say?