| 1 |
<div align="center"> |
| 2 |
<h1><code>rustix</code></h1> |
| 3 |
|
| 4 |
<p> |
| 5 |
<strong>Safe Rust bindings to POSIX/Unix/Linux/Winsock syscalls</strong> |
| 6 |
</p> |
| 7 |
|
| 8 |
<strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> project</strong> |
| 9 |
|
| 10 |
<p> |
| 11 |
<a href="https://github.com/bytecodealliance/rustix/actions?query=workflow%3ACI"><img src="https://github.com/bytecodealliance/rustix/workflows/CI/badge.svg" alt="Github Actions CI Status" /></a> |
| 12 |
<a href="https://bytecodealliance.zulipchat.com/#narrow/stream/206238-general"><img src="https://img.shields.io/badge/zulip-join_chat-brightgreen.svg" alt="zulip chat" /></a> |
| 13 |
<a href="https://crates.io/crates/rustix"><img src="https://img.shields.io/crates/v/rustix.svg" alt="crates.io page" /></a> |
| 14 |
<a href="https://docs.rs/rustix"><img src="https://docs.rs/rustix/badge.svg" alt="docs.rs docs" /></a> |
| 15 |
</p> |
| 16 |
</div> |
| 17 |
|
| 18 |
`rustix` provides efficient memory-safe and [I/O-safe] wrappers to POSIX-like, |
| 19 |
Unix-like, Linux, and Winsock syscall-like APIs, with configurable backends. |
| 20 |
It uses Rust references, slices, and return values instead of raw pointers, and |
| 21 |
[I/O safety types] instead of raw file descriptors, providing memory safety, |
| 22 |
[I/O safety], and [provenance]. It uses `Result`s for reporting errors, |
| 23 |
[`bitflags`] instead of bare integer flags, an [`Arg`] trait with optimizations |
| 24 |
to efficiently accept any Rust string type, and several other efficient |
| 25 |
conveniences. |
| 26 |
|
| 27 |
`rustix` is low-level and, and while the `net` API supports [Windows Sockets 2] |
| 28 |
(Winsock), the rest of the APIs do not support Windows; for higher-level and |
| 29 |
more portable APIs built on this functionality, see the [`cap-std`], [`memfd`], |
| 30 |
[`timerfd`], and [`io-streams`] crates, for example. |
| 31 |
|
| 32 |
`rustix` currently has two backends available: |
| 33 |
|
| 34 |
* linux_raw, which uses raw Linux system calls and vDSO calls, and is |
| 35 |
supported on Linux on x86-64, x86, aarch64, riscv64gc, powerpc64le, |
| 36 |
arm (v5 onwards), mipsel, and mips64el, with stable, nightly, and 1.63 Rust. |
| 37 |
- By being implemented entirely in Rust, avoiding `libc`, `errno`, and pthread |
| 38 |
cancellation, and employing some specialized optimizations, most functions |
| 39 |
compile down to very efficient code, which can often be fully inlined into |
| 40 |
user code. |
| 41 |
- Most functions in `linux_raw` preserve memory, I/O safety, and pointer |
| 42 |
provenance all the way down to the syscalls. |
| 43 |
|
| 44 |
* libc, which uses the [`libc`] crate which provides bindings to native `libc` |
| 45 |
libraries on Unix-family platforms, and [`windows-sys`] for Winsock on |
| 46 |
Windows, and is portable to many OS's. |
| 47 |
|
| 48 |
The linux_raw backend is enabled by default on platforms which support it. To |
| 49 |
enable the libc backend instead, either enable the "use-libc" cargo feature, |
| 50 |
or set the `RUSTFLAGS` environment variable to `--cfg=rustix_use_libc` when |
| 51 |
building. |
| 52 |
|
| 53 |
## Cargo features |
| 54 |
|
| 55 |
The modules [`rustix::io`], [`rustix::fd`], and [`rustix::ffi`] are enabled |
| 56 |
by default. The rest of the API is conditional with cargo feature flags: |
| 57 |
|
| 58 |
| Name | Description | |
| 59 |
| ---------- | -------------------------------------------------------------- | |
| 60 |
| `event` | [`rustix::event`]—Polling and event operations. | |
| 61 |
| `fs` | [`rustix::fs`]—Filesystem operations. | |
| 62 |
| `io_uring` | [`rustix::io_uring`]—Linux io_uring. | |
| 63 |
| `mm` | [`rustix::mm`]—Memory map operations. | |
| 64 |
| `mount` | [`rustix::mount`]—Linux mount API. | |
| 65 |
| `net` | [`rustix::net`]—Network-related operations. | |
| 66 |
| `param` | [`rustix::param`]—Process parameters. | |
| 67 |
| `pipe` | [`rustix::pipe`]—Pipe operations. | |
| 68 |
| `process` | [`rustix::process`]—Process-associated operations. | |
| 69 |
| `procfs` | [`rustix::procfs`]—Utilities for reading `/proc` on Linux. | |
| 70 |
| `pty` | [`rustix::pty`]—Pseudoterminal operations. | |
| 71 |
| `rand` | [`rustix::rand`]—Random-related operations. | |
| 72 |
| `shm` | [`rustix::shm`]—POSIX shared memory. | |
| 73 |
| `stdio` | [`rustix::stdio`]—Stdio-related operations. | |
| 74 |
| `system` | [`rustix::system`]—System-related operations. | |
| 75 |
| `termios` | [`rustix::termios`]—Terminal I/O stream operations. | |
| 76 |
| `thread` | [`rustix::thread`]—Thread-associated operations. | |
| 77 |
| `time` | [`rustix::time`]—Time-related operations. | |
| 78 |
| | | |
| 79 |
| `use-libc` | Enable the libc backend. | |
| 80 |
|
| 81 |
[`rustix::event`]: https://docs.rs/rustix/*/rustix/event/index.html |
| 82 |
[`rustix::fs`]: https://docs.rs/rustix/*/rustix/fs/index.html |
| 83 |
[`rustix::io_uring`]: https://docs.rs/rustix/*/rustix/io_uring/index.html |
| 84 |
[`rustix::mm`]: https://docs.rs/rustix/*/rustix/mm/index.html |
| 85 |
[`rustix::mount`]: https://docs.rs/rustix/*/rustix/mount/index.html |
| 86 |
[`rustix::net`]: https://docs.rs/rustix/*/rustix/net/index.html |
| 87 |
[`rustix::param`]: https://docs.rs/rustix/*/rustix/param/index.html |
| 88 |
[`rustix::pipe`]: https://docs.rs/rustix/*/rustix/pipe/index.html |
| 89 |
[`rustix::process`]: https://docs.rs/rustix/*/rustix/process/index.html |
| 90 |
[`rustix::procfs`]: https://docs.rs/rustix/*/rustix/procfs/index.html |
| 91 |
[`rustix::pty`]: https://docs.rs/rustix/*/rustix/pty/index.html |
| 92 |
[`rustix::rand`]: https://docs.rs/rustix/*/rustix/rand/index.html |
| 93 |
[`rustix::shm`]: https://docs.rs/rustix/*/rustix/shm/index.html |
| 94 |
[`rustix::stdio`]: https://docs.rs/rustix/*/rustix/stdio/index.html |
| 95 |
[`rustix::system`]: https://docs.rs/rustix/*/rustix/system/index.html |
| 96 |
[`rustix::termios`]: https://docs.rs/rustix/*/rustix/termios/index.html |
| 97 |
[`rustix::thread`]: https://docs.rs/rustix/*/rustix/thread/index.html |
| 98 |
[`rustix::time`]: https://docs.rs/rustix/*/rustix/time/index.html |
| 99 |
[`rustix::io`]: https://docs.rs/rustix/*/rustix/io/index.html |
| 100 |
[`rustix::fd`]: https://docs.rs/rustix/*/rustix/fd/index.html |
| 101 |
[`rustix::ffi`]: https://docs.rs/rustix/*/rustix/ffi/index.html |
| 102 |
|
| 103 |
## 64-bit Large File Support (LFS) and Year 2038 (y2038) support |
| 104 |
|
| 105 |
`rustix` automatically uses 64-bit APIs when available, and avoids exposing |
| 106 |
32-bit APIs that would have the year-2038 problem or fail to support large |
| 107 |
files. For instance, `rustix::fstatvfs` calls `fstatvfs64`, and returns a |
| 108 |
struct that's 64-bit even on 32-bit platforms. |
| 109 |
|
| 110 |
## Similar crates |
| 111 |
|
| 112 |
`rustix` is similar to [`nix`], [`simple_libc`], [`unix`], [`nc`], [`uapi`], |
| 113 |
and [`rusl`]. `rustix` is architected for [I/O safety] with most APIs using |
| 114 |
[`OwnedFd`] and [`AsFd`] to manipulate file descriptors rather than `File` or |
| 115 |
even `c_int`, and supporting multiple backends so that it can use direct |
| 116 |
syscalls while still being usable on all platforms `libc` supports. Like `nix`, |
| 117 |
`rustix` has an optimized and flexible filename argument mechanism that allows |
| 118 |
users to use a variety of string types, including non-UTF-8 string types. |
| 119 |
|
| 120 |
[`relibc`] is a similar project which aims to be a full "libc", including |
| 121 |
C-compatible interfaces and higher-level C/POSIX standard-library |
| 122 |
functionality; `rustix` just aims to provide safe and idiomatic Rust interfaces |
| 123 |
to low-level syscalls. `relibc` also doesn't tend to support features not |
| 124 |
supported on Redox, such as `*at` functions like `openat`, which are important |
| 125 |
features for `rustix`. |
| 126 |
|
| 127 |
`rustix` has its own code for making direct syscalls, similar to the |
| 128 |
[`syscall`], [`sc`], and [`scall`] crates, using the Rust `asm!` macro. |
| 129 |
`rustix` can also use Linux's vDSO mechanism to optimize Linux `clock_gettime` |
| 130 |
on all architectures, and all Linux system calls on x86. And `rustix`'s |
| 131 |
syscalls report errors using an optimized `Errno` type. |
| 132 |
|
| 133 |
`rustix`'s `*at` functions are similar to the [`openat`] crate, but `rustix` |
| 134 |
provides them as free functions rather than associated functions of a `Dir` |
| 135 |
type. `rustix`'s `CWD` constant exposes the special `AT_FDCWD` value in a safe |
| 136 |
way, so users don't need to open `.` to get a current-directory handle. |
| 137 |
|
| 138 |
`rustix`'s `openat2` function is similar to the [`openat2`] crate, but uses I/O |
| 139 |
safety types rather than `RawFd`. `rustix` does not provide dynamic feature |
| 140 |
detection, so users must handle the [`NOSYS`] error themselves. |
| 141 |
|
| 142 |
`rustix`'s `termios` module is similar to the [`termios`] crate, but uses I/O |
| 143 |
safety types rather than `RawFd`, and the flags parameters to functions such as |
| 144 |
`tcsetattr` are `enum`s rather than bare integers. And, rustix calls its |
| 145 |
`tcgetattr` function `tcgetattr`, rather than `Termios::from_fd`. |
| 146 |
|
| 147 |
## Minimum Supported Rust Version (MSRV) |
| 148 |
|
| 149 |
This crate currently works on the version of [Rust on Debian stable], which is |
| 150 |
currently [Rust 1.63]. This policy may change in the future, in minor version |
| 151 |
releases, so users using a fixed version of Rust should pin to a specific |
| 152 |
version of this crate. |
| 153 |
|
| 154 |
## Minimum Linux Version |
| 155 |
|
| 156 |
On Linux platforms, rustix requires at least Linux 3.2. This is at most the |
| 157 |
oldest Linux version supported by: |
| 158 |
- [any current Rust target], or |
| 159 |
- [kernel.org] at the time of rustix's [MSRV] release. |
| 160 |
The specifics of this policy may change in the future, but we intend it to |
| 161 |
always reflect “very old” Linux versions. |
| 162 |
|
| 163 |
[MSRV]: #minimum-supported-rust-version-msrv |
| 164 |
[Rust 1.63]: https://blog.rust-lang.org/2022/08/11/Rust-1.63.0.html |
| 165 |
[any current Rust target]: https://doc.rust-lang.org/nightly/rustc/platform-support.html |
| 166 |
[kernel.org]: https://www.kernel.org/releases.html |
| 167 |
[Rust on Debian stable]: https://packages.debian.org/stable/rust/rustc |
| 168 |
[Windows Sockets 2]: https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-start-page-2 |
| 169 |
[`nix`]: https://crates.io/crates/nix |
| 170 |
[`unix`]: https://crates.io/crates/unix |
| 171 |
[`nc`]: https://crates.io/crates/nc |
| 172 |
[`simple_libc`]: https://crates.io/crates/simple_libc |
| 173 |
[`uapi`]: https://crates.io/crates/uapi |
| 174 |
[`rusl`]: https://lib.rs/crates/rusl |
| 175 |
[`relibc`]: https://gitlab.redox-os.org/redox-os/relibc |
| 176 |
[`syscall`]: https://crates.io/crates/syscall |
| 177 |
[`sc`]: https://crates.io/crates/sc |
| 178 |
[`scall`]: https://crates.io/crates/scall |
| 179 |
[`openat`]: https://crates.io/crates/openat |
| 180 |
[`openat2`]: https://crates.io/crates/openat2 |
| 181 |
[I/O safety types]: https://doc.rust-lang.org/stable/std/os/fd/index.html#structs |
| 182 |
[`termios`]: https://crates.io/crates/termios |
| 183 |
[`libc`]: https://crates.io/crates/libc |
| 184 |
[`windows-sys`]: https://crates.io/crates/windows-sys |
| 185 |
[`cap-std`]: https://crates.io/crates/cap-std |
| 186 |
[`memfd`]: https://crates.io/crates/memfd |
| 187 |
[`timerfd`]: https://crates.io/crates/timerfd |
| 188 |
[`io-streams`]: https://crates.io/crates/io-streams |
| 189 |
[`bitflags`]: https://crates.io/crates/bitflags |
| 190 |
[`Arg`]: https://docs.rs/rustix/*/rustix/path/trait.Arg.html |
| 191 |
[I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md |
| 192 |
[I/O safety]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md |
| 193 |
[provenance]: https://github.com/rust-lang/rust/issues/95228 |
| 194 |
[`OwnedFd`]: https://doc.rust-lang.org/stable/std/os/fd/struct.OwnedFd.html |
| 195 |
[`AsFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.AsFd.html |
| 196 |
[`NOSYS`]: https://docs.rs/rustix/*/rustix/io/struct.Errno.html#associatedconstant.NOSYS |