Crates.io | rustix |
lib.rs | rustix |
version | 0.38.41 |
source | src |
created_at | 2021-10-29 10:44:45.767768 |
updated_at | 2024-11-18 20:07:11.89854 |
description | Safe Rust bindings to POSIX/Unix/Linux/Winsock-like syscalls |
homepage | |
repository | https://github.com/bytecodealliance/rustix |
max_upload_size | |
id | 473904 |
size | 2,120,646 |
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 Result
s 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.63 Rust.
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.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=rustix_use_libc
when
building.
The modules rustix::io
, rustix::fd
, and rustix::ffi
are enabled by
default. The rest of the API is conditional with cargo feature flags:
Name | Description |
---|---|
event |
rustix::event —Polling and event operations. |
fs |
rustix::fs —Filesystem operations. |
io_uring |
rustix::io_uring —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. |
procfs |
rustix::procfs —Utilities for reading /proc on Linux. |
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. |
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.
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
syscall
, 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 enum
s rather than bare integers. And, rustix calls its
tcgetattr
function tcgetattr
, rather than Termios::from_fd
.
This crate currently works on the version of Rust on Debian stable, which is currently Rust 1.63. This policy may change in the future, in minor version releases, so users using a fixed version of Rust should pin to a specific version of this crate.
On Linux platforms, rustix requires at least Linux 3.2. This is at most the oldest Linux version supported by: