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, 19Unix-like, Linux, and Winsock syscall-like APIs, with configurable backends. 20It 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 24to efficiently accept any Rust string type, and several other efficient 25conveniences. 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 29more 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 48The linux_raw backend is enabled by default on platforms which support it. To 49enable the libc backend instead, either enable the "use-libc" cargo feature, 50or set the `RUSTFLAGS` environment variable to `--cfg=rustix_use_libc` when 51building. 52 53## Cargo features 54 55The modules [`rustix::io`], [`rustix::fd`], and [`rustix::ffi`] are enabled 56by 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 10632-bit APIs that would have the year-2038 problem or fail to support large 107files. For instance, `rustix::fstatvfs` calls `fstatvfs64`, and returns a 108struct 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`], 113and [`rusl`]. `rustix` is architected for [I/O safety] with most APIs using 114[`OwnedFd`] and [`AsFd`] to manipulate file descriptors rather than `File` or 115even `c_int`, and supporting multiple backends so that it can use direct 116syscalls while still being usable on all platforms `libc` supports. Like `nix`, 117`rustix` has an optimized and flexible filename argument mechanism that allows 118users 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 121C-compatible interfaces and higher-level C/POSIX standard-library 122functionality; `rustix` just aims to provide safe and idiomatic Rust interfaces 123to low-level syscalls. `relibc` also doesn't tend to support features not 124supported on Redox, such as `*at` functions like `openat`, which are important 125features 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` 130on all architectures, and all Linux system calls on x86. And `rustix`'s 131syscalls report errors using an optimized `Errno` type. 132 133`rustix`'s `*at` functions are similar to the [`openat`] crate, but `rustix` 134provides them as free functions rather than associated functions of a `Dir` 135type. `rustix`'s `CWD` constant exposes the special `AT_FDCWD` value in a safe 136way, 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 139safety types rather than `RawFd`. `rustix` does not provide dynamic feature 140detection, so users must handle the [`NOSYS`] error themselves. 141 142`rustix`'s `termios` module is similar to the [`termios`] crate, but uses I/O 143safety 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 149This crate currently works on the version of [Rust on Debian stable], which is 150currently [Rust 1.63]. This policy may change in the future, in minor version 151releases, so users using a fixed version of Rust should pin to a specific 152version of this crate. 153 154## Minimum Linux Version 155 156On Linux platforms, rustix requires at least Linux 3.2. This is at most the 157oldest Linux version supported by: 158 - [any current Rust target], or 159 - [kernel.org] at the time of rustix's [MSRV] release. 160The specifics of this policy may change in the future, but we intend it to 161always 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 197
