rustix

rustix provides efficient, memory-safe, and I/O-safe Rust bindings to POSIX, Unix, Linux, and Winsock syscalls. It is designed to provide high-performance wrappers that use Rust-native types like references, slices, and Results instead of raw pointers and integer error codes.

Key features include:

• I/O Safety: Uses OwnedFd and AsFd instead of raw file descriptors.
• Memory Safety: Uses Rust's ownership and type system to ensure safety.
• Efficient Argument Handling: Uses an Arg trait to efficiently accept various Rust string types (including non-UTF-8).
• Configurable Backends: Supports both a high-performance linux_raw backend and a portable libc backend.

Note: While the net API supports Windows Sockets 2 (Winsock), most other APIs are not intended for Windows. For higher-level portable APIs, consider crates like cap-std, memfd, timerfd, or io-streams.

rustix provides efficient, memory-safe, and I/O-safe wrappers to POSIX-like, Unix-like, Linux, and Winsock syscall-like APIs. It abstracts away many of the historical complexities and safety issues associated with raw C-style syscalls.

Key improvements include:

• Error Handling: Translates error values into Rust Results.
• Memory Safety: Buffers are passed as Rust slices, and out-parameters are returned as values.
• I/O Safety: Uses AsFd and OwnedFd instead of bare integers to manage file descriptors.
• Path Handling: Uses the Arg type, allowing path arguments to accept various string types.
• Large File Support (LFS): Automatically uses 64-bit types (e.g., u64, i64) for file sizes and offsets, providing Year 2038 (y2038) compatibility.
• Type Safety: Uses enums and bitflags for constants and flags.
• Simplified APIs: De-multiplexes functions like fcntl and ioctl, and presents variadic functions (like openat) as non-variadic.
• Automatic Memory Management: Functions returning strings automatically allocate sufficient memory and retry syscalls as needed.

Note: rustix does not hide significant platform differences, detect runtime support (except for y2038/LFS), or provide sandboxing/ambient authority restrictions. For those features, consider cap-std or system-interface.

# #[cfg(feature = "net")]
# fn read(sock: std::net::TcpStream, buf: &mut [u8]) -> std::io::Result<()> {
# use rustix::net::RecvFlags;
let (nread, _received) = rustix::net::recv(&sock, buf, RecvFlags::PEEK)?;
# let _ = nread;
# Ok(())
# }

The Buffer trait is used by rustix I/O functions (like read) to determine how data is returned to the caller. The type of buffer you pass dictates the return type of the function:

Supported types include mutable slices (&mut [T]), mutable arrays (&mut [T; N]), Vec<T> (with alloc feature), and slices of uninitialized memory (&mut [MaybeUninit<T>]).

// Passing a &mut [u8]
let mut buf = [0_u8; 64];
let nread = read(fd, &mut buf)?;

// Passing a &mut [MaybeUninit<u8>]
let mut buf = [MaybeUninit::<u8>::uninit(); 64];
let (init, uninit) = read(fd, &mut buf)?;

// Passing SpareCapacity
let mut buf = Vec::with_capacity(64);
let nread = read(fd, spare_capacity(&mut buf))?;

RawDir is a low-level directory iterator implemented using the getdents system call. It allows you to iterate over directory entries (including . and ..) using a provided buffer.

Important Constraints

• Fixed Buffer Size: This implementation does not automatically grow the buffer. If the buffer is too small to hold the next entry (e.g., due to a very long filename), next() may return an error (specifically Errno::INVAL).
• Resizing Strategy: To handle arbitrarily large filenames, you must catch the error, drop the current iterator, resize your buffer, and create a new RawDir iterator. The iterator is guaranteed to continue where it left off if the file descriptor remains the same.

Usage Patterns

Using a Heap-allocated Buffer (Simple)

This approach is suitable if you can assume a maximum filename length.

use std::mem::MaybeUninit;
use rustix::fs::{CWD, Mode, OFlags, openat, RawDir};
use rustix::cstr;

let fd = openat(
    CWD,
    cstr!("."),
    OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC,
    Mode::empty(),
)
.unwrap();

let mut buf = Vec::with_capacity(8192);
let mut iter = RawDir::new(fd, buf.spare_capacity_mut());
while let Some(entry) = iter.next() {
    let entry = entry.unwrap();
    dbg!(&entry);
}

Using a Portable Growing Buffer

This pattern handles entries with arbitrarily large filenames by catching Errno::INVAL and resizing the buffer.

use std::mem::MaybeUninit;
use rustix::fs::{CWD, Mode, OFlags, openat, RawDir};
use rustix::io::Errno;
use rustix::cstr;

let fd = openat(
    CWD,
    cstr!("."),
    OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC,
    Mode::empty(),
)
.unwrap();

let mut buf = Vec::with_capacity(8192);
'read: loop {
    'resize: {
        let mut iter = RawDir::new(&fd, buf.spare_capacity_mut());
        while let Some(entry) = iter.next() {
            let entry = match entry {
                Err(Errno::INVAL) => break 'resize,
                r => r.unwrap(),
            };
            dbg!(&entry);
        }
        break 'read;
    }

    let new_capacity = buf.capacity() * 2;
    buf.reserve(new_capacity);
}

The following Cargo features control which API modules are available. The modules rustix::io, rustix::buffer, rustix::fd, rustix::ffi, and rustix::ioctl are enabled by default.