rsix

Safe Rust ("rs") bindings to POSIX-like/Unix-like/Linux ("ix") syscalls

A Bytecode Alliance project

rsix (formerly known as posish) provides efficient memory-safe and I/O-safe wrappers to POSIX-like, Unix-like, and Linux syscall APIs, with configurable backends. It uses Rust references, slices, and return values instead of raw pointers, and io-lifetimes instead of raw file descriptors, providing memory safety and I/O safety. 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.

rsix is low-level and does not support Windows; for higher-level and more portable APIs built on this functionality, see the system-interface, cap-std, and fs-set-times crates, for example.

rsix currently has two backends available: linux_raw and libc.

The linux_raw backend is enabled by default on Linux on x86-64, x86, aarch64, riscv64gc and arm (v5 onwards), and uses raw Linux system calls and vDSO calls. It supports stable as well as nightly 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. On nightly Rust, they can often be fully inlined into user code.
• Most functions in linux_raw preserve memory and I/O safety all the way down to the syscalls.
• linux_raw uses a 64-bit time_t type on all platforms, avoiding the y2038 bug.

The libc backend is enabled by default on all other platforms, and can be set explicitly for any target by setting RUSTFLAGS to --cfg rsix_use_libc. It uses the libc crate which provides bindings to native libc libraries and is portable to many OS's.

Similar crates

rsix is similar to nix, simple_libc, unix, and nc. rsix is a relatively new project with less overall coverage, 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, rsix 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; rsix 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 rsix.

rsix has its own code for making direct syscalls, similar to the sc and scall crates, though rsix currently only supports direct syscalls on Linux on x86_64, x86, aarch64, and riscv64. rsix can use either the unstable Rust asm! macro or out-of-line .s files so it supports both Stable and Nightly Rust. rsix's syscalls report errors using an optimized Error type, and rsix supports Linux's vDSO mechanism to optimize Linux clock_gettime on all architectures, and all Linux system calls on x86.

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

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