Repository files navigation

rustix provides efficient memory-safe andI/O-safe wrappers to POSIX-like,Unix-like, Linux, and Winsock syscall-like APIs, with configurable backends. Ituses Rust references, slices, and return values instead of raw pointers, andI/O safety types instead of raw file descriptors, providing memory safety,I/O safety, andprovenance. It usesResults for reporting errors,bitflags instead of bare integer flags, anArg trait with optimizationsto efficiently accept any Rust string type, and several other efficientconveniences.

rustix is low-level and, and while thenet API supportsWindows Sockets 2(Winsock), the rest of the APIs do not support Windows; for higher-level andmore portable APIs built on this functionality, see thecap-std,memfd,timerfd, andio-streams crates, for example.

rustix currently has two backends available:

• linux_raw, which uses raw Linux system calls and vDSO calls, and issupported on Linux on x86-64, x86, aarch64, riscv64gc, powerpc64le,arm (v5 onwards), mipsel, and mips64el, with stable, nightly, and 1.63 Rust.

  • By being implemented entirely in Rust, avoidinglibc,errno, and pthreadcancellation, and employing some specialized optimizations, most functionscompile down to very efficient code, which can often be fully inlined intouser code.
  • Most functions inlinux_raw preserve memory, I/O safety, and pointerprovenance all the way down to the syscalls.

• libc, which uses thelibc crate which provides bindings to nativelibclibraries on Unix-family platforms, andwindows-sys for Winsock onWindows, and is portable to many OS's.

The linux_raw backend is enabled by default on platforms which support it. Toenable the libc backend instead, either enable the "use-libc" cargo feature, orset theRUSTFLAGS environment variable to--cfg=rustix_use_libc whenbuilding.

The modulesrustix::io,rustix::buffer,rustix::fd,rustix::ffi, andrustix::ioctl are enabled by default. The rest of theAPI modules are conditional with cargo feature flags.

rustix automatically uses 64-bit APIs when available, and avoids exposing32-bit APIs that would have the year-2038 problem or fail to support largefiles. For instance,rustix::fstatvfs callsfstatvfs64, and returns astruct that's 64-bit even on 32-bit platforms.

rustix is similar tonix,simple_libc,unix,nc,uapi,andrusl.rustix is architected forI/O safety with most APIs usingOwnedFd andAsFd to manipulate file descriptors rather thanFile orevenc_int, and supporting multiple backends so that it can use directsyscalls while still being usable on all platformslibc supports. Likenix,rustix has an optimized and flexible filename argument mechanism that allowsusers 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", includingC-compatible interfaces and higher-level C/POSIX standard-libraryfunctionality;rustix just aims to provide safe and idiomatic Rust interfacesto low-level syscalls.relibc also doesn't tend to support features notsupported on Redox, such as*at functions likeopenat, which are importantfeatures forrustix.

rustix has its own code for making direct syscalls, similar to thesyscall,sc, andscall crates, using the Rustasm! macro.rustix can also use Linux's vDSO mechanism to optimize Linuxclock_gettimeon all architectures, and all Linux system calls on x86. Andrustix'ssyscalls report errors using an optimizedErrno type.

rustix's*at functions are similar to theopenat crate, butrustixprovides them as free functions rather than associated functions of aDirtype.rustix'sCWD constant exposes the specialAT_FDCWD value in a safeway, so users don't need to open. to get a current-directory handle.

rustix'sopenat2 function is similar to theopenat2 crate, but uses I/Osafety types rather thanRawFd.rustix does not provide dynamic featuredetection, so users must handle theNOSYS error themselves.

rustix'stermios module is similar to thetermios crate, but uses I/Osafety types rather thanRawFd, and the flags parameters to functions such astcsetattr areenums rather than bare integers. And, rustix calls itstcgetattr functiontcgetattr, rather thanTermios::from_fd.

This crate currently works on the version ofRust on Debian stable, which iscurrentlyRust 1.63. This policy may change in the future, in minor versionreleases, so users using a fixed version of Rust should pin to a specificversion of this crate.

On Linux platforms, rustix requires at least Linux 3.2. This is at most theoldest Linux version supported by:

• any current Rust target, or
• kernel.org at the time of rustix'sMSRV release.The specifics of this policy may change in the future, but we intend it toalways reflect “very old” Linux versions.