# Crate rustix

source · [−]
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 `Result`s.
- 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 `enum`s 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.

## Modules

fd

Export the `*Fd` types and traits that are used in rustix’s public API.

ffi

Utilities related to FFI bindings.

io

I/O operations.

termios

Terminal I/O stream operations.

## Macros

cstr

A macro for `CStr` literals.