rustix

rustix provides efficient memory-safe and [I/O-safe] wrappers to POSIX-like, Unix-like, Linux, and Winsock syscall-like APIs, with configurable backends. It uses Rust references, slices, and return values instead of raw pointers, and [I/O safety types] instead of raw file descriptors, providing memory safety, [I/O safety], and [provenance]. It uses Results for reporting errors, [bitflags] instead of bare integer flags, an [Arg] trait with optimizations to efficiently accept any Rust string type, and several other efficient conveniences.

rustix is low-level and, and while the net API supports [Windows Sockets 2] (Winsock), the rest of the APIs do not support Windows; for higher-level and more portable APIs built on this functionality, see the [cap-std], [memfd], [timerfd], and [io-streams] crates, for example.

rustix currently has two backends available:

* linux_raw, which uses raw Linux system calls and vDSO calls, and is supported on Linux on x86-64, x86, aarch64, riscv64gc, powerpc64le, arm (v5 onwards), mipsel, and mips64el, with stable, nightly, and 1.65 Rust. - By being implemented entirely in Rust, avoiding libc, errno, and pthread cancellation, and employing some specialized optimizations, most functions compile down to very efficient code, which can often be fully inlined into user code. - Most functions in linux_raw preserve memory, I/O safety, and pointer provenance all the way down to the syscalls.

* libc, which uses the [libc] crate which provides bindings to native libc libraries on Unix-family platforms, and [windows-sys] for Winsock on Windows, and is portable to many OS's.

The linux_raw backend is enabled by default on platforms which support it. To enable the libc backend instead, either enable the "use-libc" cargo feature, or set the RUSTFLAGS environment variable to --cfg=rustixuselibc when building.

Cargo features

The modules [rustix::io], [rustix::buffer], [rustix::fd], [rustix::ffi], and [rustix::ioctl] are enabled by default. The rest of the API modules are conditional with cargo feature flags.

| Name | Description | | ---------- | -------------------------------------------------------------- | | event | [rustix::event]—Polling and event operations. | | fs | [rustix::fs]—Filesystem operations. | | iouring | [rustix::iouring]—Linux io_uring. | | mm | [rustix::mm]—Memory map operations. | | mount | [rustix::mount]—Linux mount API. | | net | [rustix::net]—Network-related operations. | | param | [rustix::param]—Process parameters. | | pipe | [rustix::pipe]—Pipe operations. | | process | [rustix::process]—Process-associated operations. | | pty | [rustix::pty]—Pseudoterminal operations. | | rand | [rustix::rand]—Random-related operations. | | shm | [rustix::shm]—POSIX shared memory. | | stdio | [rustix::stdio]—Stdio-related operations. | | system | [rustix::system]—System-related operations. | | termios | [rustix::termios]—Terminal I/O stream operations. | | thread | [rustix::thread]—Thread-associated operations. | | time | [rustix::time]—Time-related operations. | | | | | use-libc | Enable the libc backend. | | | | | linux411 | Enable optimizations that assume Linux ≥ 4.11 | | linux51 | Enable optimizations that assume Linux ≥ 5.1 | | linux511 | Enable optimizations that assume Linux ≥ 5.11 | | linux_latest | Enable optimizations that assume the latest Linux release | | | | | use-libc-auxv | Use getauxval instead of PRGETAUXV or "/proc/self/auxv". | | | | | std | On by default; disable to activate #![no_std]. | | alloc | On by default; enables features that depend on [alloc]. |

[rustix::buffer]: https://docs.rs/rustix/*/rustix/buffer/index.html [rustix::event]: https://docs.rs/rustix/*/rustix/event/index.html [rustix::fs]: https://docs.rs/rustix/*/rustix/fs/index.html [rustix::iouring]: https://docs.rs/rustix/*/rustix/iouring/index.html [rustix::mm]: https://docs.rs/rustix/*/rustix/mm/index.html [rustix::mount]: https://docs.rs/rustix/*/rustix/mount/index.html [rustix::net]: https://docs.rs/rustix/*/rustix/net/index.html [rustix::param]: https://docs.rs/rustix/*/rustix/param/index.html [rustix::pipe]: https://docs.rs/rustix/*/rustix/pipe/index.html [rustix::process]: https://docs.rs/rustix/*/rustix/process/index.html [rustix::pty]: https://docs.rs/rustix/*/rustix/pty/index.html [rustix::rand]: https://docs.rs/rustix/*/rustix/rand/index.html [rustix::shm]: https://docs.rs/rustix/*/rustix/shm/index.html [rustix::stdio]: https://docs.rs/rustix/*/rustix/stdio/index.html [rustix::system]: https://docs.rs/rustix/*/rustix/system/index.html [rustix::termios]: https://docs.rs/rustix/*/rustix/termios/index.html [rustix::thread]: https://docs.rs/rustix/*/rustix/thread/index.html [rustix::time]: https://docs.rs/rustix/*/rustix/time/index.html [rustix::io]: https://docs.rs/rustix/*/rustix/io/index.html [rustix::fd]: https://docs.rs/rustix/*/rustix/fd/index.html [rustix::ffi]: https://docs.rs/rustix/*/rustix/ffi/index.html [rustix::ioctl]: https://docs.rs/rustix/*/rustix/ffi/ioctl.html

64-bit Large File Support (LFS) and Year 2038 (y2038) support

rustix automatically uses 64-bit APIs when available, and avoids exposing 32-bit APIs that would have the year-2038 problem or fail to support large files. For instance, rustix::fstatvfs calls fstatvfs64, and returns a struct that's 64-bit even on 32-bit platforms.

Similar crates

rustix is similar to [nix], [simple_libc], [unix], [nc], [uapi], and [rusl]. rustix is architected for [I/O safety] with most APIs using [OwnedFd] and [AsFd] to manipulate file descriptors rather than File or even c_int, and supporting multiple backends so that it can use direct syscalls while still being usable on all platforms libc supports. Like nix, rustix has an optimized and flexible filename argument mechanism that allows users to use a variety of string types, including non-UTF-8 string types.

[relibc] is a similar project which aims to be a full "libc", including C-compatible interfaces and higher-level C/POSIX standard-library functionality; rustix just aims to provide safe and idiomatic Rust interfaces to low-level syscalls. relibc also doesn't tend to support features not supported on Redox, such as *at functions like openat, which are important features for rustix.

rustix has its own code for making direct syscalls, similar to the [sc], and [scall] crates, using the Rust asm! macro. rustix can also use Linux's vDSO mechanism to optimize Linux clock_gettime on all architectures, and all Linux system calls on x86. And rustix's syscalls report errors using an optimized Errno type.

rustix's *at functions are similar to the [openat] crate, but rustix provides them as free functions rather than associated functions of a Dir type. rustix's CWD constant exposes the special AT_FDCWD value in a safe way, so users don't need to open . to get a current-directory handle.

rustix's openat2 function is similar to the [openat2] crate, but uses I/O safety types rather than RawFd. rustix does not provide dynamic feature detection, so users must handle the [NOSYS] error themselves.

rustix's termios module is similar to the [termios] crate, but uses I/O safety types rather than RawFd, and the flags parameters to functions such as tcsetattr are enums rather than bare integers. And, rustix calls its tcgetattr function tcgetattr, rather than Termios::from_fd.

Minimum Supported Rust Version

This crate has a Minimum Supported Rust Version (MSRV) of [Rust 1.65].

The current policy is that the minimum Rust version required to use this crate may be increased in minor releases.

Minimum Linux Version

On Linux platforms, rustix requires at least Linux 3.2. This is at most the oldest Linux version supported by: - [any current Rust target], or - [kernel.org] at the time of rustix's [MSRV] release. The specifics of this policy may change in the future, but we intend it to always reflect “very old” Linux versions.

[MSRV]: #minimum-supported-rust-version [Rust 1.65]: https://blog.rust-lang.org/2022/11/03/Rust-1.65.0/ [any current Rust target]: https://doc.rust-lang.org/nightly/rustc/platform-support.html [kernel.org]: https://www.kernel.org/releases.html [Windows Sockets 2]: https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-start-page-2 [nix]: https://crates.io/crates/nix [unix]: https://crates.io/crates/unix [nc]: https://crates.io/crates/nc [simplelibc]: https://crates.io/crates/simplelibc [uapi]: https://crates.io/crates/uapi [rusl]: https://lib.rs/crates/rusl [relibc]: https://gitlab.redox-os.org/redox-os/relibc [sc]: https://crates.io/crates/sc [scall]: https://crates.io/crates/scall [openat]: https://crates.io/crates/openat [openat2]: https://crates.io/crates/openat2 [I/O safety types]: https://doc.rust-lang.org/stable/std/os/fd/index.html#structs [termios]: https://crates.io/crates/termios [libc]: https://crates.io/crates/libc [windows-sys]: https://crates.io/crates/windows-sys [cap-std]: https://crates.io/crates/cap-std [memfd]: https://crates.io/crates/memfd [timerfd]: https://crates.io/crates/timerfd [io-streams]: https://crates.io/crates/io-streams [bitflags]: https://crates.io/crates/bitflags [Arg]: https://docs.rs/rustix/*/rustix/path/trait.Arg.html [I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md [I/O safety]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md [provenance]: https://github.com/rust-lang/rust/issues/95228 [OwnedFd]: https://doc.rust-lang.org/stable/std/os/fd/struct.OwnedFd.html [AsFd]: https://doc.rust-lang.org/stable/std/os/fd/trait.AsFd.html [NOSYS]: https://docs.rs/rustix/*/rustix/io/struct.Errno.html#associatedconstant.NOSYS [alloc]: https://doc.rust-lang.org/alloc/alloc/index.html