rustix/
lib.rs

1// wasip2 conditionally gates stdlib APIs such as `OsStrExt`.
2// https://github.com/rust-lang/rust/issues/130323
3#![cfg_attr(
4    all(
5        target_os = "wasi",
6        target_env = "p2",
7        any(feature = "fs", feature = "mount", feature = "net")
8    ),
9    feature(wasip2)
10)]
11//! `rustix` provides efficient memory-safe and [I/O-safe] wrappers to
12//! POSIX-like, Unix-like, Linux, and Winsock syscall-like APIs, with
13//! configurable backends.
14//!
15//! With rustix, you can write code like this:
16//!
17//! ```
18//! # #[cfg(feature = "net")]
19//! # fn read(sock: std::net::TcpStream, buf: &mut [u8]) -> std::io::Result<()> {
20//! # use rustix::net::RecvFlags;
21//! let nread: usize = rustix::net::recv(&sock, buf, RecvFlags::PEEK)?;
22//! # let _ = nread;
23//! # Ok(())
24//! # }
25//! ```
26//!
27//! instead of like this:
28//!
29//! ```
30//! # #[cfg(feature = "net")]
31//! # fn read(sock: std::net::TcpStream, buf: &mut [u8]) -> std::io::Result<()> {
32//! # #[cfg(unix)]
33//! # use std::os::unix::io::AsRawFd;
34//! # #[cfg(target_os = "wasi")]
35//! # use std::os::wasi::io::AsRawFd;
36//! # #[cfg(windows)]
37//! # use windows_sys::Win32::Networking::WinSock as libc;
38//! # #[cfg(windows)]
39//! # use std::os::windows::io::AsRawSocket;
40//! # const MSG_PEEK: i32 = libc::MSG_PEEK;
41//! let nread: usize = unsafe {
42//!     #[cfg(any(unix, target_os = "wasi"))]
43//!     let raw = sock.as_raw_fd();
44//!     #[cfg(windows)]
45//!     let raw = sock.as_raw_socket();
46//!     match libc::recv(
47//!         raw as _,
48//!         buf.as_mut_ptr().cast(),
49//!         buf.len().try_into().unwrap_or(i32::MAX as _),
50//!         MSG_PEEK,
51//!     ) {
52//!         -1 => return Err(std::io::Error::last_os_error()),
53//!         nread => nread as usize,
54//!     }
55//! };
56//! # let _ = nread;
57//! # Ok(())
58//! # }
59//! ```
60//!
61//! rustix's APIs perform the following tasks:
62//!  - Error values are translated to [`Result`]s.
63//!  - Buffers are passed as Rust slices.
64//!  - Out-parameters are presented as return values.
65//!  - Path arguments use [`Arg`], so they accept any string type.
66//!  - File descriptors are passed and returned via [`AsFd`] and [`OwnedFd`]
67//!    instead of bare integers, ensuring I/O safety.
68//!  - Constants use `enum`s and [`bitflags`] types, and enable [support for
69//!    externally defined flags].
70//!  - Multiplexed functions (eg. `fcntl`, `ioctl`, etc.) are de-multiplexed.
71//!  - Variadic functions (eg. `openat`, etc.) are presented as non-variadic.
72//!  - Functions that return strings automatically allocate sufficient memory
73//!    and retry the syscall as needed to determine the needed length.
74//!  - Functions and types which need `l` prefixes or `64` suffixes to enable
75//!    large-file support (LFS) are used automatically. File sizes and offsets
76//!    are always presented as `u64` and `i64`.
77//!  - Behaviors that depend on the sizes of C types like `long` are hidden.
78//!  - In some places, more human-friendly and less historical-accident names
79//!    are used (and documentation aliases are used so that the original names
80//!    can still be searched for).
81//!  - Provide y2038 compatibility, on platforms which support this.
82//!  - Correct selected platform bugs, such as behavioral differences when
83//!    running under seccomp.
84//!  - Use `timespec` for timestamps instead of `timeval`.
85//!
86//! Things they don't do include:
87//!  - Detecting whether functions are supported at runtime, except in specific
88//!    cases where new interfaces need to be detected to support y2038 and LFS.
89//!  - Hiding significant differences between platforms.
90//!  - Restricting ambient authorities.
91//!  - Imposing sandboxing features such as filesystem path or network address
92//!    sandboxing.
93//!
94//! See [`cap-std`], [`system-interface`], and [`io-streams`] for libraries
95//! which do hide significant differences between platforms, and [`cap-std`]
96//! which does perform sandboxing and restricts ambient authorities.
97//!
98//! [`cap-std`]: https://crates.io/crates/cap-std
99//! [`system-interface`]: https://crates.io/crates/system-interface
100//! [`io-streams`]: https://crates.io/crates/io-streams
101//! [`getrandom`]: https://crates.io/crates/getrandom
102//! [`bitflags`]: https://crates.io/crates/bitflags
103//! [`AsFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.AsFd.html
104//! [`OwnedFd`]: https://doc.rust-lang.org/stable/std/os/fd/struct.OwnedFd.html
105//! [I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md
106//! [`Result`]: https://doc.rust-lang.org/stable/std/result/enum.Result.html
107//! [`Arg`]: https://docs.rs/rustix/*/rustix/path/trait.Arg.html
108//! [support for externally defined flags]: https://docs.rs/bitflags/*/bitflags/#externally-defined-flags
109
110#![deny(missing_docs)]
111#![allow(stable_features)]
112#![cfg_attr(linux_raw, deny(unsafe_code))]
113#![cfg_attr(rustc_attrs, feature(rustc_attrs))]
114#![cfg_attr(docsrs, feature(doc_cfg))]
115#![cfg_attr(all(wasi_ext, target_os = "wasi", feature = "std"), feature(wasi_ext))]
116#![cfg_attr(core_ffi_c, feature(core_ffi_c))]
117#![cfg_attr(core_c_str, feature(core_c_str))]
118#![cfg_attr(all(feature = "alloc", alloc_c_string), feature(alloc_c_string))]
119#![cfg_attr(all(feature = "alloc", alloc_ffi), feature(alloc_ffi))]
120#![cfg_attr(not(feature = "std"), no_std)]
121#![cfg_attr(feature = "rustc-dep-of-std", feature(ip))]
122#![cfg_attr(feature = "rustc-dep-of-std", allow(internal_features))]
123#![cfg_attr(
124    any(feature = "rustc-dep-of-std", core_intrinsics),
125    feature(core_intrinsics)
126)]
127#![cfg_attr(asm_experimental_arch, feature(asm_experimental_arch))]
128#![cfg_attr(not(feature = "all-apis"), allow(dead_code))]
129// It is common in Linux and libc APIs for types to vary between platforms.
130#![allow(clippy::unnecessary_cast)]
131// It is common in Linux and libc APIs for types to vary between platforms.
132#![allow(clippy::useless_conversion)]
133// Redox and WASI have enough differences that it isn't worth precisely
134// conditionalizing all the `use`s for them. Similar for if we don't have
135// "all-apis".
136#![cfg_attr(
137    any(target_os = "redox", target_os = "wasi", not(feature = "all-apis")),
138    allow(unused_imports)
139)]
140
141#[cfg(all(feature = "rustc-dep-of-std", feature = "alloc"))]
142extern crate rustc_std_workspace_alloc as alloc;
143
144#[cfg(all(feature = "alloc", not(feature = "rustc-dep-of-std")))]
145extern crate alloc;
146
147// Use `static_assertions` macros if we have them, or a polyfill otherwise.
148#[cfg(all(test, static_assertions))]
149#[macro_use]
150#[allow(unused_imports)]
151extern crate static_assertions;
152#[cfg(all(test, not(static_assertions)))]
153#[macro_use]
154#[allow(unused_imports)]
155mod static_assertions;
156
157// Internal utilities.
158mod buffer;
159#[cfg(not(windows))]
160#[macro_use]
161pub(crate) mod cstr;
162#[macro_use]
163pub(crate) mod utils;
164// Polyfill for `std` in `no_std` builds.
165#[cfg_attr(feature = "std", path = "maybe_polyfill/std/mod.rs")]
166#[cfg_attr(not(feature = "std"), path = "maybe_polyfill/no_std/mod.rs")]
167pub(crate) mod maybe_polyfill;
168#[cfg(test)]
169#[macro_use]
170pub(crate) mod check_types;
171#[macro_use]
172pub(crate) mod bitcast;
173
174// linux_raw: Weak symbols are used by the use-libc-auxv feature for
175// glibc 2.15 support.
176//
177// libc: Weak symbols are used to call various functions available in some
178// versions of libc and not others.
179#[cfg(any(
180    all(linux_raw, feature = "use-libc-auxv"),
181    all(libc, not(any(windows, target_os = "espidf", target_os = "wasi")))
182))]
183#[macro_use]
184mod weak;
185
186// Pick the backend implementation to use.
187#[cfg_attr(libc, path = "backend/libc/mod.rs")]
188#[cfg_attr(linux_raw, path = "backend/linux_raw/mod.rs")]
189#[cfg_attr(wasi, path = "backend/wasi/mod.rs")]
190mod backend;
191
192/// Export the `*Fd` types and traits that are used in rustix's public API.
193///
194/// Users can use this to avoid needing to import anything else to use the same
195/// versions of these types and traits.
196pub mod fd {
197    use super::backend;
198
199    // Re-export `AsSocket` etc. too, as users can't implement `AsFd` etc. on
200    // Windows due to them having blanket impls on Windows, so users must
201    // implement `AsSocket` etc.
202    #[cfg(windows)]
203    pub use backend::fd::{AsRawSocket, AsSocket, FromRawSocket, IntoRawSocket};
204
205    pub use backend::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd};
206}
207
208// The public API modules.
209#[cfg(feature = "event")]
210#[cfg_attr(docsrs, doc(cfg(feature = "event")))]
211pub mod event;
212pub mod ffi;
213#[cfg(not(windows))]
214#[cfg(feature = "fs")]
215#[cfg_attr(docsrs, doc(cfg(feature = "fs")))]
216pub mod fs;
217pub mod io;
218#[cfg(linux_kernel)]
219#[cfg(feature = "io_uring")]
220#[cfg_attr(docsrs, doc(cfg(feature = "io_uring")))]
221pub mod io_uring;
222pub mod ioctl;
223#[cfg(not(any(windows, target_os = "espidf", target_os = "vita", target_os = "wasi")))]
224#[cfg(feature = "mm")]
225#[cfg_attr(docsrs, doc(cfg(feature = "mm")))]
226pub mod mm;
227#[cfg(linux_kernel)]
228#[cfg(feature = "mount")]
229#[cfg_attr(docsrs, doc(cfg(feature = "mount")))]
230pub mod mount;
231#[cfg(not(any(target_os = "redox", target_os = "wasi")))]
232#[cfg(feature = "net")]
233#[cfg_attr(docsrs, doc(cfg(feature = "net")))]
234pub mod net;
235#[cfg(not(any(windows, target_os = "espidf")))]
236#[cfg(feature = "param")]
237#[cfg_attr(docsrs, doc(cfg(feature = "param")))]
238pub mod param;
239#[cfg(not(windows))]
240#[cfg(any(feature = "fs", feature = "mount", feature = "net"))]
241#[cfg_attr(
242    docsrs,
243    doc(cfg(any(feature = "fs", feature = "mount", feature = "net")))
244)]
245pub mod path;
246#[cfg(feature = "pipe")]
247#[cfg_attr(docsrs, doc(cfg(feature = "pipe")))]
248#[cfg(not(any(windows, target_os = "wasi")))]
249pub mod pipe;
250#[cfg(not(windows))]
251#[cfg(feature = "process")]
252#[cfg_attr(docsrs, doc(cfg(feature = "process")))]
253pub mod process;
254#[cfg(feature = "procfs")]
255#[cfg(linux_kernel)]
256#[cfg_attr(docsrs, doc(cfg(feature = "procfs")))]
257pub mod procfs;
258#[cfg(not(windows))]
259#[cfg(not(target_os = "wasi"))]
260#[cfg(feature = "pty")]
261#[cfg_attr(docsrs, doc(cfg(feature = "pty")))]
262pub mod pty;
263#[cfg(not(windows))]
264#[cfg(feature = "rand")]
265#[cfg_attr(docsrs, doc(cfg(feature = "rand")))]
266pub mod rand;
267#[cfg(not(any(
268    windows,
269    target_os = "android",
270    target_os = "espidf",
271    target_os = "vita",
272    target_os = "wasi"
273)))]
274#[cfg(feature = "shm")]
275#[cfg_attr(docsrs, doc(cfg(feature = "shm")))]
276pub mod shm;
277#[cfg(not(windows))]
278#[cfg(feature = "stdio")]
279#[cfg_attr(docsrs, doc(cfg(feature = "stdio")))]
280pub mod stdio;
281#[cfg(feature = "system")]
282#[cfg(not(any(windows, target_os = "wasi")))]
283#[cfg_attr(docsrs, doc(cfg(feature = "system")))]
284pub mod system;
285#[cfg(not(any(windows, target_os = "vita")))]
286#[cfg(feature = "termios")]
287#[cfg_attr(docsrs, doc(cfg(feature = "termios")))]
288pub mod termios;
289#[cfg(not(windows))]
290#[cfg(feature = "thread")]
291#[cfg_attr(docsrs, doc(cfg(feature = "thread")))]
292pub mod thread;
293#[cfg(not(any(windows, target_os = "espidf")))]
294#[cfg(feature = "time")]
295#[cfg_attr(docsrs, doc(cfg(feature = "time")))]
296pub mod time;
297
298// "runtime" is also a public API module, but it's only for libc-like users.
299#[cfg(not(windows))]
300#[cfg(feature = "runtime")]
301#[cfg(linux_raw)]
302#[cfg_attr(not(document_experimental_runtime_api), doc(hidden))]
303#[cfg_attr(docsrs, doc(cfg(feature = "runtime")))]
304pub mod runtime;
305
306// Temporarily provide some mount functions for use in the fs module for
307// backwards compatibility.
308#[cfg(linux_kernel)]
309#[cfg(all(feature = "fs", not(feature = "mount")))]
310pub(crate) mod mount;
311
312// Declare "fs" as a non-public module if "fs" isn't enabled but we need it for
313// reading procfs.
314#[cfg(not(windows))]
315#[cfg(not(feature = "fs"))]
316#[cfg(all(
317    linux_raw,
318    not(feature = "use-libc-auxv"),
319    not(feature = "use-explicitly-provided-auxv"),
320    any(
321        feature = "param",
322        feature = "process",
323        feature = "runtime",
324        feature = "time",
325        target_arch = "x86",
326    )
327))]
328#[cfg_attr(docsrs, doc(cfg(feature = "fs")))]
329pub(crate) mod fs;
330
331// Similarly, declare `path` as a non-public module if needed.
332#[cfg(not(windows))]
333#[cfg(not(any(feature = "fs", feature = "mount", feature = "net")))]
334#[cfg(all(
335    linux_raw,
336    not(feature = "use-libc-auxv"),
337    not(feature = "use-explicitly-provided-auxv"),
338    any(
339        feature = "param",
340        feature = "process",
341        feature = "runtime",
342        feature = "time",
343        target_arch = "x86",
344    )
345))]
346pub(crate) mod path;
347
348// Private modules used by multiple public modules.
349#[cfg(not(any(windows, target_os = "espidf")))]
350#[cfg(any(feature = "thread", feature = "time", target_arch = "x86"))]
351mod clockid;
352#[cfg(not(any(windows, target_os = "wasi")))]
353#[cfg(any(
354    feature = "procfs",
355    feature = "process",
356    feature = "runtime",
357    feature = "termios",
358    feature = "thread",
359    all(bsd, feature = "event"),
360    all(linux_kernel, feature = "net")
361))]
362mod pid;
363#[cfg(any(feature = "process", feature = "thread"))]
364#[cfg(linux_kernel)]
365mod prctl;
366#[cfg(not(any(windows, target_os = "espidf", target_os = "wasi")))]
367#[cfg(any(feature = "process", feature = "runtime", all(bsd, feature = "event")))]
368mod signal;
369#[cfg(any(
370    feature = "fs",
371    feature = "process",
372    feature = "runtime",
373    feature = "thread",
374    feature = "time",
375    all(feature = "event", any(bsd, linux_kernel, windows, target_os = "wasi")),
376    all(
377        linux_raw,
378        not(feature = "use-libc-auxv"),
379        not(feature = "use-explicitly-provided-auxv"),
380        any(
381            feature = "param",
382            feature = "process",
383            feature = "runtime",
384            feature = "time",
385            target_arch = "x86",
386        )
387    )
388))]
389mod timespec;
390#[cfg(not(any(windows, target_os = "wasi")))]
391#[cfg(any(
392    feature = "fs",
393    feature = "process",
394    feature = "thread",
395    all(
396        linux_raw,
397        not(feature = "use-libc-auxv"),
398        not(feature = "use-explicitly-provided-auxv"),
399        any(
400            feature = "param",
401            feature = "runtime",
402            feature = "time",
403            target_arch = "x86",
404        )
405    ),
406    all(linux_kernel, feature = "net")
407))]
408mod ugid;
rustix/lib.rs

rustix/
lib.rs
