Skip to main content

rustix/
lib.rs

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