Trait AsCStrArray

Source

pub unsafe trait AsCStrArray: Sealed {
    // Required method
    fn as_ptr(&self) -> *const *const c_char;

    // Provided methods
    fn as_mut_ptr(&mut self) -> *const *mut c_char { ... }
    fn to_vec(&self) -> Vec<CString> { ... }
}

Expand description

Abstraction over an array of C-style strings, for arguments to Exec::execve

The native execve system call expects two arrays of C-style strings, which must be passed as pointers to null-terminated arrays of pointers to null-terminated byte strings. This trait abstracts over how ownership and lifetime of these arrays and strings are managed in Rust, allowing different types to be used as long as they can provide the required pointer to the array of C-style strings. The main requirement is that the array must be null-terminated and that the pointers in the array must point to valid C-style strings. Implementations of Exec::execve can then use this trait to accept different types of string arrays and to obtain the required pointers for the system call without needing to know the details of how the strings are stored or managed in Rust.

This trait is sealed to prevent external implementations, as the safety guarantees of the methods depend on the implementor upholding certain invariants about the pointers and the lifetime of the strings.

See also IntoCStrArray for types that can be converted into a AsCStrArray.

Required Methods§

Source

fn as_ptr(&self) -> const const c_char

Returns a pointer to the array of C-style strings.

The array must be null-terminated, i.e., the last pointer in the array must be a null pointer. Each pointer in the array must point to a valid C-style string (i.e., a null-terminated sequence of bytes). The array and strings must remain valid and unmodified until self is mutated or dropped. The caller must not mutate the array or strings through this pointer.

Provided Methods§

Source

fn as_mut_ptr(&mut self) -> const mut c_char

Returns a pointer to the array of C-style strings.

This method just returns the same pointer as as_ptr, but with a different type signature. The mutability of the pointer is only for matching the expected type signature of execve and does not imply that the strings can actually be mutated through this pointer. The caller must not mutate the array or strings through this pointer. The array and strings must remain valid and unmodified until self is mutated or dropped.

Source

fn to_vec(&self) -> Vec<CString>

Constructs a Vec<CString> from the array of C-style strings.

This method is a convenience for converting the array of C-style strings into a more Rust-friendly format. It iterates over the pointers in the array, converts each C-style string into a CString, and collects them into a Vec<CString>. The returned Vec<CString> owns the new allocations for the array and strings, so it is safe to use and modify independently of self.