1 | //! `rustix` provides efficient memory-safe and [I/O-safe] wrappers to |
2 | //! POSIX-like, Unix-like, Linux, and Winsock2 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: usize = 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: usize = 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 | //! |
75 | //! Things they don't do include: |
76 | //! - Detecting whether functions are supported at runtime, except in specific |
77 | //! cases where new interfaces need to be detected to support y2038 and LFS. |
78 | //! - Hiding significant differences between platforms. |
79 | //! - Restricting ambient authorities. |
80 | //! - Imposing sandboxing features such as filesystem path or network address |
81 | //! sandboxing. |
82 | //! |
83 | //! See [`cap-std`], [`system-interface`], and [`io-streams`] for libraries |
84 | //! which do hide significant differences between platforms, and [`cap-std`] |
85 | //! which does perform sandboxing and restricts ambient authorities. |
86 | //! |
87 | //! [`cap-std`]: https://crates.io/crates/cap-std |
88 | //! [`system-interface`]: https://crates.io/crates/system-interface |
89 | //! [`io-streams`]: https://crates.io/crates/io-streams |
90 | //! [`getrandom`]: https://crates.io/crates/getrandom |
91 | //! [`bitflags`]: https://crates.io/crates/bitflags |
92 | //! [`AsFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.AsFd.html |
93 | //! [`OwnedFd`]: https://doc.rust-lang.org/stable/std/os/fd/struct.OwnedFd.html |
94 | //! [I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md |
95 | //! [`Result`]: https://doc.rust-lang.org/stable/std/result/enum.Result.html |
96 | //! [`Arg`]: https://docs.rs/rustix/*/rustix/path/trait.Arg.html |
97 | //! [support for externally defined flags]: https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags |
98 | |
99 | #![deny (missing_docs)] |
100 | #![allow (stable_features)] |
101 | #![cfg_attr (linux_raw, deny(unsafe_code))] |
102 | #![cfg_attr (rustc_attrs, feature(rustc_attrs))] |
103 | #![cfg_attr (doc_cfg, feature(doc_cfg))] |
104 | #![cfg_attr (all(wasi_ext, target_os = "wasi" , feature = "std" ), feature(wasi_ext))] |
105 | #![cfg_attr (core_ffi_c, feature(core_ffi_c))] |
106 | #![cfg_attr (core_c_str, feature(core_c_str))] |
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 (asm_experimental_arch, feature(asm_experimental_arch))] |
117 | #![cfg_attr (not(feature = "all-apis" ), allow(dead_code))] |
118 | // It is common in linux and libc APIs for types to vary between platforms. |
119 | #![allow (clippy::unnecessary_cast)] |
120 | // It is common in linux and libc APIs for types to vary between platforms. |
121 | #![allow (clippy::useless_conversion)] |
122 | // Redox and WASI have enough differences that it isn't worth precisely |
123 | // conditionalizing all the `use`s for them. |
124 | #![cfg_attr (any(target_os = "redox" , target_os = "wasi" ), allow(unused_imports))] |
125 | |
126 | #[cfg (all(feature = "alloc" , not(feature = "rustc-dep-of-std" )))] |
127 | extern crate alloc; |
128 | |
129 | // Use `static_assertions` macros if we have them, or a polyfill otherwise. |
130 | #[cfg (all(test, static_assertions))] |
131 | #[macro_use ] |
132 | #[allow (unused_imports)] |
133 | extern crate static_assertions; |
134 | #[cfg (all(test, not(static_assertions)))] |
135 | #[macro_use ] |
136 | #[allow (unused_imports)] |
137 | mod static_assertions; |
138 | |
139 | // Internal utilities. |
140 | #[cfg (not(windows))] |
141 | #[macro_use ] |
142 | pub(crate) mod cstr; |
143 | #[macro_use ] |
144 | pub(crate) mod utils; |
145 | // Polyfill for `std` in `no_std` builds. |
146 | #[cfg_attr (feature = "std" , path = "maybe_polyfill/std/mod.rs" )] |
147 | #[cfg_attr (not(feature = "std" ), path = "maybe_polyfill/no_std/mod.rs" )] |
148 | pub(crate) mod maybe_polyfill; |
149 | #[cfg (test)] |
150 | #[macro_use ] |
151 | pub(crate) mod check_types; |
152 | #[macro_use ] |
153 | pub(crate) mod bitcast; |
154 | |
155 | // linux_raw: Weak symbols are used by the use-libc-auxv feature for |
156 | // glibc 2.15 support. |
157 | // |
158 | // libc: Weak symbols are used to call various functions available in some |
159 | // versions of libc and not others. |
160 | #[cfg (any( |
161 | all(linux_raw, feature = "use-libc-auxv" ), |
162 | all(libc, not(any(windows, target_os = "espidf" , target_os = "wasi" ))) |
163 | ))] |
164 | #[macro_use ] |
165 | mod weak; |
166 | |
167 | // Pick the backend implementation to use. |
168 | #[cfg_attr (libc, path = "backend/libc/mod.rs" )] |
169 | #[cfg_attr (linux_raw, path = "backend/linux_raw/mod.rs" )] |
170 | #[cfg_attr (wasi, path = "backend/wasi/mod.rs" )] |
171 | mod backend; |
172 | |
173 | /// Export the `*Fd` types and traits that are used in rustix's public API. |
174 | /// |
175 | /// Users can use this to avoid needing to import anything else to use the same |
176 | /// versions of these types and traits. |
177 | pub mod fd { |
178 | use super::backend; |
179 | |
180 | // Re-export `AsSocket` etc. too, as users can't implement `AsFd` etc. on |
181 | // Windows due to them having blanket impls on Windows, so users must |
182 | // implement `AsSocket` etc. |
183 | #[cfg (windows)] |
184 | pub use backend::fd::{AsRawSocket, AsSocket, FromRawSocket, IntoRawSocket}; |
185 | |
186 | pub use backend::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; |
187 | } |
188 | |
189 | // The public API modules. |
190 | #[cfg (feature = "event" )] |
191 | #[cfg_attr (doc_cfg, doc(cfg(feature = "event" )))] |
192 | pub mod event; |
193 | #[cfg (not(windows))] |
194 | pub mod ffi; |
195 | #[cfg (not(windows))] |
196 | #[cfg (feature = "fs" )] |
197 | #[cfg_attr (doc_cfg, doc(cfg(feature = "fs" )))] |
198 | pub mod fs; |
199 | pub mod io; |
200 | #[cfg (linux_kernel)] |
201 | #[cfg (feature = "io_uring" )] |
202 | #[cfg_attr (doc_cfg, doc(cfg(feature = "io_uring" )))] |
203 | pub mod io_uring; |
204 | pub mod ioctl; |
205 | #[cfg (not(any(windows, target_os = "espidf" , target_os = "wasi" )))] |
206 | #[cfg (feature = "mm" )] |
207 | #[cfg_attr (doc_cfg, doc(cfg(feature = "mm" )))] |
208 | pub mod mm; |
209 | #[cfg (linux_kernel)] |
210 | #[cfg (feature = "mount" )] |
211 | #[cfg_attr (doc_cfg, doc(cfg(feature = "mount" )))] |
212 | pub mod mount; |
213 | #[cfg (not(any(target_os = "redox" , target_os = "wasi" )))] |
214 | #[cfg (feature = "net" )] |
215 | #[cfg_attr (doc_cfg, doc(cfg(feature = "net" )))] |
216 | pub mod net; |
217 | #[cfg (not(any(windows, target_os = "espidf" )))] |
218 | #[cfg (feature = "param" )] |
219 | #[cfg_attr (doc_cfg, doc(cfg(feature = "param" )))] |
220 | pub mod param; |
221 | #[cfg (not(windows))] |
222 | #[cfg (any(feature = "fs" , feature = "mount" , feature = "net" ))] |
223 | #[cfg_attr ( |
224 | doc_cfg, |
225 | doc(cfg(any(feature = "fs" , feature = "mount" , feature = "net" ))) |
226 | )] |
227 | pub mod path; |
228 | #[cfg (feature = "pipe" )] |
229 | #[cfg_attr (doc_cfg, doc(cfg(feature = "pipe" )))] |
230 | #[cfg (not(any(windows, target_os = "wasi" )))] |
231 | pub mod pipe; |
232 | #[cfg (not(windows))] |
233 | #[cfg (feature = "process" )] |
234 | #[cfg_attr (doc_cfg, doc(cfg(feature = "process" )))] |
235 | pub mod process; |
236 | #[cfg (feature = "procfs" )] |
237 | #[cfg (linux_kernel)] |
238 | #[cfg_attr (doc_cfg, doc(cfg(feature = "procfs" )))] |
239 | pub mod procfs; |
240 | #[cfg (not(windows))] |
241 | #[cfg (not(target_os = "wasi" ))] |
242 | #[cfg (feature = "pty" )] |
243 | #[cfg_attr (doc_cfg, doc(cfg(feature = "pty" )))] |
244 | pub mod pty; |
245 | #[cfg (not(windows))] |
246 | #[cfg (feature = "rand" )] |
247 | #[cfg_attr (doc_cfg, doc(cfg(feature = "rand" )))] |
248 | pub mod rand; |
249 | #[cfg (not(any( |
250 | windows, |
251 | target_os = "android" , |
252 | target_os = "espidf" , |
253 | target_os = "wasi" |
254 | )))] |
255 | #[cfg (feature = "shm" )] |
256 | #[cfg_attr (doc_cfg, doc(cfg(feature = "shm" )))] |
257 | pub mod shm; |
258 | #[cfg (not(windows))] |
259 | #[cfg (feature = "stdio" )] |
260 | #[cfg_attr (doc_cfg, doc(cfg(feature = "stdio" )))] |
261 | pub mod stdio; |
262 | #[cfg (feature = "system" )] |
263 | #[cfg (not(any(windows, target_os = "wasi" )))] |
264 | #[cfg_attr (doc_cfg, doc(cfg(feature = "system" )))] |
265 | pub mod system; |
266 | #[cfg (not(windows))] |
267 | #[cfg (feature = "termios" )] |
268 | #[cfg_attr (doc_cfg, doc(cfg(feature = "termios" )))] |
269 | pub mod termios; |
270 | #[cfg (not(windows))] |
271 | #[cfg (feature = "thread" )] |
272 | #[cfg_attr (doc_cfg, doc(cfg(feature = "thread" )))] |
273 | pub mod thread; |
274 | #[cfg (not(any(windows, target_os = "espidf" )))] |
275 | #[cfg (feature = "time" )] |
276 | #[cfg_attr (doc_cfg, doc(cfg(feature = "time" )))] |
277 | pub mod time; |
278 | |
279 | // "runtime" is also a public API module, but it's only for libc-like users. |
280 | #[cfg (not(windows))] |
281 | #[cfg (feature = "runtime" )] |
282 | #[cfg (linux_raw)] |
283 | #[cfg_attr (not(document_experimental_runtime_api), doc(hidden))] |
284 | #[cfg_attr (doc_cfg, doc(cfg(feature = "runtime" )))] |
285 | pub mod runtime; |
286 | |
287 | // Temporarily provide some mount functions for use in the fs module for |
288 | // backwards compatibility. |
289 | #[cfg (linux_kernel)] |
290 | #[cfg (all(feature = "fs" , not(feature = "mount" )))] |
291 | pub(crate) mod mount; |
292 | |
293 | // Declare "fs" as a non-public module if "fs" isn't enabled but we need it for |
294 | // reading procfs. |
295 | #[cfg (not(windows))] |
296 | #[cfg (not(feature = "fs" ))] |
297 | #[cfg (all( |
298 | linux_raw, |
299 | not(feature = "use-libc-auxv" ), |
300 | not(feature = "use-explicitly-provided-auxv" ), |
301 | any( |
302 | feature = "param" , |
303 | feature = "runtime" , |
304 | feature = "time" , |
305 | target_arch = "x86" , |
306 | ) |
307 | ))] |
308 | #[cfg_attr (doc_cfg, doc(cfg(feature = "fs" )))] |
309 | pub(crate) mod fs; |
310 | |
311 | // Similarly, declare `path` as a non-public module if needed. |
312 | #[cfg (not(windows))] |
313 | #[cfg (not(any(feature = "fs" , feature = "mount" , feature = "net" )))] |
314 | #[cfg (all( |
315 | linux_raw, |
316 | not(feature = "use-libc-auxv" ), |
317 | not(feature = "use-explicitly-provided-auxv" ), |
318 | any( |
319 | feature = "param" , |
320 | feature = "runtime" , |
321 | feature = "time" , |
322 | target_arch = "x86" , |
323 | ) |
324 | ))] |
325 | pub(crate) mod path; |
326 | |
327 | // Private modules used by multiple public modules. |
328 | #[cfg (not(any(windows, target_os = "espidf" )))] |
329 | #[cfg (any(feature = "thread" , feature = "time" , target_arch = "x86" ))] |
330 | mod clockid; |
331 | #[cfg (not(any(windows, target_os = "wasi" )))] |
332 | #[cfg (any( |
333 | feature = "procfs" , |
334 | feature = "process" , |
335 | feature = "runtime" , |
336 | feature = "termios" , |
337 | feature = "thread" , |
338 | all(bsd, feature = "event" ), |
339 | all(linux_kernel, feature = "net" ) |
340 | ))] |
341 | mod pid; |
342 | #[cfg (any(feature = "process" , feature = "thread" ))] |
343 | #[cfg (linux_kernel)] |
344 | mod prctl; |
345 | #[cfg (not(any(windows, target_os = "espidf" , target_os = "wasi" )))] |
346 | #[cfg (any(feature = "process" , feature = "runtime" , all(bsd, feature = "event" )))] |
347 | mod signal; |
348 | #[cfg (not(windows))] |
349 | #[cfg (any( |
350 | feature = "fs" , |
351 | feature = "runtime" , |
352 | feature = "thread" , |
353 | feature = "time" , |
354 | all( |
355 | linux_raw, |
356 | not(feature = "use-libc-auxv" ), |
357 | not(feature = "use-explicitly-provided-auxv" ), |
358 | any( |
359 | feature = "param" , |
360 | feature = "runtime" , |
361 | feature = "time" , |
362 | target_arch = "x86" , |
363 | ) |
364 | ) |
365 | ))] |
366 | mod timespec; |
367 | #[cfg (not(any(windows, target_os = "wasi" )))] |
368 | #[cfg (any( |
369 | feature = "fs" , |
370 | feature = "process" , |
371 | feature = "thread" , |
372 | all( |
373 | linux_raw, |
374 | not(feature = "use-libc-auxv" ), |
375 | not(feature = "use-explicitly-provided-auxv" ), |
376 | any( |
377 | feature = "param" , |
378 | feature = "runtime" , |
379 | feature = "time" , |
380 | target_arch = "x86" , |
381 | ) |
382 | ), |
383 | all(linux_kernel, feature = "net" ) |
384 | ))] |
385 | mod ugid; |
386 | |