Crate rustix

source ·
Expand description

rustix provides efficient memory-safe and I/O-safe wrappers to POSIX-like, Unix-like, Linux, and Winsock 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, and enable support for externally defined flags.
  • Multiplexed functions (eg. fcntl, ioctl, etc.) are de-multiplexed.
  • Variadic functions (eg. openat, etc.) are presented as non-variadic.
  • Functions that return strings automatically allocate sufficient memory and retry the syscall as needed to determine the needed length.
  • Functions and types which need l prefixes or 64 suffixes to enable large-file support (LFS) are used automatically. File sizes and offsets are always 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.
  • Use timespec for timestamps instead of timeval.

Things they don’t do include:

  • Detecting whether functions are supported at runtime, except in specific cases where new interfaces need to be detected to support y2038 and LFS.
  • 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.

Modules§

  • backend 🔒
    The linux_raw backend.
  • bitcast 🔒
    The bitcast and bitflags_bits macros.
  • buffer 🔒
    Utilities to help with buffering.
  • clockid 🔒
  • cstr 🔒
  • event
    Event operations.
  • fd
    Export the *Fd types and traits that are used in rustix’s public API.
  • ffi
    Utilities related to FFI bindings.
  • fs
    Filesystem operations.
  • io
    I/O operations.
  • ioctl
    Unsafe ioctl API.
  • maybe_polyfill 🔒
    Imports from std that would be polyfilled for no_std builds (see src/polyfill/no_std).
  • mount 🔒
    Linux mount API.
  • net
    Network-related operations.
  • path
    Filesystem path operations.
  • pid 🔒
    The Pid type.
  • pipe
    pipe and related APIs.
  • prctl 🔒
    Helper functions for prctl syscalls.
  • process
    Process-associated operations.
  • shm
    POSIX shared memory
  • signal 🔒
  • system
    Uname and other system-level functions.
  • thread
    Thread-associated operations.
  • time
    Time-related operations.
  • timespec 🔒
    Timespec and related types, which are used by multiple public API modules.
  • ugid 🔒
    User and Group ID types.
  • utils 🔒
    Miscellaneous minor utilities.
  • weak 🔒
    Support for “weak linkage” to symbols on Unix

Macros§