mozilla-central/third_party/rust/rustix/README.md

Source code

Revision control

Copy as Markdown

Other Tools

<div align="center">
<h1><code>rustix</code></h1>
<p>
<strong>Safe Rust bindings to POSIX/Unix/Linux/Winsock syscalls</strong>
</p>
<strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> project</strong>
<p>
<a href="https://crates.io/crates/rustix"><img src="https://img.shields.io/crates/v/rustix.svg" alt="crates.io page" /></a>
<a href="https://docs.rs/rustix"><img src="https://docs.rs/rustix/badge.svg" alt="docs.rs docs" /></a>
</p>
</div>
`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.
- 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=rustix_use_libc` when
building.
## Cargo features
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. |
## 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
[`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`.
## Minimum Supported Rust Version (MSRV)
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.
## 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-msrv