1[
2 {
3 "Name": "rustix",
4 "License": "Apache-2.0_WITH_LLVM-exception, Apache License 2.0, MIT",
5 "License File": "LICENSE-Apache-2.0_WITH_LLVM-exception|LICENSE-APACHE|LICENSE-MIT",
6 "Version Number": "0.36.8",
7 "Owner": "fangting12@huawei.com",
8 "Upstream URL": "https://github.com/bytecodealliance/rustix",
9 "Description": "A Rust library that provides support for working with UTF-8 encoded strings."
10 }
11]
12
README.md
1<div align="center">
2 <h1><code>rustix</code></h1>
3
4 <p>
5 <strong>Safe Rust bindings to POSIX/Unix/Linux/Winsock2 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 Winsock2 syscall-like APIs, with configurable backends.
20It uses Rust references, slices, and return values instead of raw pointers, and
21[`io-lifetimes`] 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 Winsock2 on
28Windows, the rest of the APIs do not support Windows; for higher-level and more
29portable APIs built on this functionality, see the [`system-interface`],
30[`cap-std`], and [`fs-set-times`] 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.48 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. On nightly Rust, they can often be
40 fully inlined into 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 Winsock2 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| `fs` | [`rustix::fs`] and [`rustix::path`]—Filesystem operations.
61| `io_uring` | [`rustix::io_uring`]—Linux io_uring.
62| `mm` | [`rustix::mm`]—Memory map operations.
63| `net` | [`rustix::net`] and [`rustix::path`]—Network-related operations.
64| `param` | [`rustix::param`]—Process parameters.
65| `process` | [`rustix::process`]—Process-associated operations.
66| `rand` | [`rustix::rand`]—Random-related operations.
67| `termios` | [`rustix::termios`]—Terminal I/O stream operations.
68| `thread` | [`rustix::thread`]—Thread-associated operations.
69| `time` | [`rustix::time`]—Time-related operations.
70| |
71| `use-libc` | Enable the libc backend.
72
73[`rustix::fs`]: https://docs.rs/rustix/latest/rustix/fs/index.html
74[`rustix::io_uring`]: https://docs.rs/rustix/latest/rustix/io_uring/index.html
75[`rustix::mm`]: https://docs.rs/rustix/latest/rustix/mm/index.html
76[`rustix::net`]: https://docs.rs/rustix/latest/rustix/net/index.html
77[`rustix::param`]: https://docs.rs/rustix/latest/rustix/param/index.html
78[`rustix::process`]: https://docs.rs/rustix/latest/rustix/process/index.html
79[`rustix::rand`]: https://docs.rs/rustix/latest/rustix/rand/index.html
80[`rustix::termios`]: https://docs.rs/rustix/latest/rustix/termios/index.html
81[`rustix::thread`]: https://docs.rs/rustix/latest/rustix/thread/index.html
82[`rustix::time`]: https://docs.rs/rustix/latest/rustix/time/index.html
83[`rustix::io`]: https://docs.rs/rustix/latest/rustix/io/index.html
84[`rustix::fd`]: https://docs.rs/rustix/latest/rustix/fd/index.html
85[`rustix::ffi`]: https://docs.rs/rustix/latest/rustix/ffi/index.html
86[`rustix::path`]: https://docs.rs/rustix/latest/rustix/path/index.html
87
88## Similar crates
89
90`rustix` is similar to [`nix`], [`simple_libc`], [`unix`], [`nc`], and
91[`uapi`]. `rustix` is architected for [I/O safety] with most APIs using
92[`OwnedFd`] and [`AsFd`] to manipulate file descriptors rather than `File` or
93even `c_int`, and supporting multiple backends so that it can use direct
94syscalls while still being usable on all platforms `libc` supports. Like `nix`,
95`rustix` has an optimized and flexible filename argument mechanism that allows
96users to use a variety of string types, including non-UTF-8 string types.
97
98[`relibc`] is a similar project which aims to be a full "libc", including
99C-compatible interfaces and higher-level C/POSIX standard-library
100functionality; `rustix` just aims to provide safe and idiomatic Rust interfaces
101to low-level syscalls. `relibc` also doesn't tend to support features not
102supported on Redox, such as `*at` functions like `openat`, which are important
103features for `rustix`.
104
105`rustix` has its own code for making direct syscalls, similar to the [`sc`] and
106[`scall`] crates, though `rustix` can use either the Rust `asm!` macro or
107out-of-line `.s` files so it supports Rust versions from 1.48 through Nightly.
108`rustix` can also use Linux's vDSO mechanism to optimize Linux `clock_gettime`
109on all architectures, and all Linux system calls on x86. And `rustix`'s
110syscalls report errors using an optimized `Errno` type.
111
112`rustix`'s `*at` functions are similar to the [`openat`] crate, but `rustix`
113provides them as free functions rather than associated functions of a `Dir`
114type. `rustix`'s `cwd()` function exposes the special `AT_FDCWD` value in a safe
115way, so users don't need to open `.` to get a current-directory handle.
116
117`rustix`'s `openat2` function is similar to the [`openat2`] crate, but uses
118I/O safety types rather than `RawFd`. `rustix` does not provide dynamic feature
119detection, so users must handle the [`NOSYS`] error themselves.
120
121`rustix`'s `termios` module is similar to the [`termios`] crate, but uses
122I/O safety types rather than `RawFd`, and the flags parameters to functions
123such as `tcsetattr` are `enum`s rather than bare integers. And, rustix calls
124its `tcgetattr` function `tcgetattr`, rather than `Termios::from_fd`.
125
126## Minimum Supported Rust Version (MSRV)
127
128This crate currently works on the version of [Rust on Debian stable], which is
129currently Rust 1.48. This policy may change in the future, in minor version
130releases, so users using a fixed version of Rust should pin to a specific
131version of this crate.
132
133[Rust on Debian stable]: https://packages.debian.org/stable/rust/rustc
134[`nix`]: https://crates.io/crates/nix
135[`unix`]: https://crates.io/crates/unix
136[`nc`]: https://crates.io/crates/nc
137[`simple_libc`]: https://crates.io/crates/simple_libc
138[`uapi`]: https://crates.io/crates/uapi
139[`relibc`]: https://github.com/redox-os/relibc
140[`syscall`]: https://crates.io/crates/syscall
141[`sc`]: https://crates.io/crates/sc
142[`scall`]: https://crates.io/crates/scall
143[`system-interface`]: https://crates.io/crates/system-interface
144[`openat`]: https://crates.io/crates/openat
145[`openat2`]: https://crates.io/crates/openat2
146[`fs-set-times`]: https://crates.io/crates/fs-set-times
147[`io-lifetimes`]: https://crates.io/crates/io-lifetimes
148[`termios`]: https://crates.io/crates/termios
149[`libc`]: https://crates.io/crates/libc
150[`windows-sys`]: https://crates.io/crates/windows-sys
151[`cap-std`]: https://crates.io/crates/cap-std
152[`bitflags`]: https://crates.io/crates/bitflags
153[`Arg`]: https://docs.rs/rustix/latest/rustix/path/trait.Arg.html
154[I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md
155[I/O safety]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md
156[provenance]: https://github.com/rust-lang/rust/issues/95228
157[`OwnedFd`]: https://docs.rs/io-lifetimes/latest/io_lifetimes/struct.OwnedFd.html
158[`AsFd`]: https://docs.rs/io-lifetimes/latest/io_lifetimes/trait.AsFd.html
159[`NOSYS`]: https://docs.rs/rustix/latest/rustix/io/struct.Errno.html#associatedconstant.NOSYS
160
