Crate rustix

Expand description

rustix provides efficient memory-safe and I/O-safe wrappers to POSIX-like, Unix-like, Linux, and Winsock2 syscall-like APIs, with configurable backends.

With rustix, you can write code like this:

let nread: usize = rustix::net::recv(&sock, buf, RecvFlags::PEEK)?;

instead of like this:

let nread: usize = unsafe {
    #[cfg(any(unix, target_os = "wasi"))]
    let raw = sock.as_raw_fd();
    #[cfg(windows)]
    let raw = sock.as_raw_socket();
    match libc::recv(
        raw as _,
        buf.as_mut_ptr().cast(),
        buf.len().try_into().unwrap_or(i32::MAX as _),
        MSG_PEEK,
    ) {
        -1 => return Err(std::io::Error::last_os_error()),
        nread => nread as usize,
    }
};

rustix’s APIs perform the following tasks:

Error values are translated to Results.
Buffers are passed as Rust slices.
Out-parameters are presented as return values.
Path arguments use Arg, so they accept any string type.
File descriptors are passed and returned via AsFd and OwnedFd instead of bare integers, ensuring I/O safety.
Constants use enums and bitflags types.
Multiplexed functions (eg. fcntl, ioctl, etc.) are de-multiplexed.
Variadic functions (eg. openat, etc.) are presented as non-variadic.
Functions and types which need l prefixes or 64 suffixes to enable large-file support are used automatically, and file sizes and offsets are presented as u64 and i64.
Behaviors that depend on the sizes of C types like long are hidden.
In some places, more human-friendly and less historical-accident names are used (and documentation aliases are used so that the original names can still be searched for).
Provide y2038 compatibility, on platforms which support this.
Correct selected platform bugs, such as behavioral differences when running under seccomp.

Things they don’t do include:

Detecting whether functions are supported at runtime.
Hiding significant differences between platforms.
Restricting ambient authorities.
Imposing sandboxing features such as filesystem path or network address sandboxing.

See cap-std, system-interface, and io-streams for libraries which do hide significant differences between platforms, and cap-std which does perform sandboxing and restricts ambient authorities.