| 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: 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/*/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. Similar for if we don't have |
| 124 |
// "all-apis". |
| 125 |
#![cfg_attr( |
| 126 |
any(target_os = "redox", target_os = "wasi", not(feature = "all-apis")), |
| 127 |
allow(unused_imports) |
| 128 |
)] |
| 129 |
|
| 130 |
#[cfg(all(feature = "alloc", not(feature = "rustc-dep-of-std")))] |
| 131 |
extern crate alloc; |
| 132 |
|
| 133 |
// Use `static_assertions` macros if we have them, or a polyfill otherwise. |
| 134 |
#[cfg(all(test, static_assertions))] |
| 135 |
#[macro_use] |
| 136 |
#[allow(unused_imports)] |
| 137 |
extern crate static_assertions; |
| 138 |
#[cfg(all(test, not(static_assertions)))] |
| 139 |
#[macro_use] |
| 140 |
#[allow(unused_imports)] |
| 141 |
mod static_assertions; |
| 142 |
|
| 143 |
// Internal utilities. |
| 144 |
mod buffer; |
| 145 |
#[cfg(not(windows))] |
| 146 |
#[macro_use] |
| 147 |
pub(crate) mod cstr; |
| 148 |
#[macro_use] |
| 149 |
pub(crate) mod utils; |
| 150 |
// Polyfill for `std` in `no_std` builds. |
| 151 |
#[cfg_attr(feature = "std", path = "maybe_polyfill/std/mod.rs")] |
| 152 |
#[cfg_attr(not(feature = "std"), path = "maybe_polyfill/no_std/mod.rs")] |
| 153 |
pub(crate) mod maybe_polyfill; |
| 154 |
#[cfg(test)] |
| 155 |
#[macro_use] |
| 156 |
pub(crate) mod check_types; |
| 157 |
#[macro_use] |
| 158 |
pub(crate) mod bitcast; |
| 159 |
|
| 160 |
// linux_raw: Weak symbols are used by the use-libc-auxv feature for |
| 161 |
// glibc 2.15 support. |
| 162 |
// |
| 163 |
// libc: Weak symbols are used to call various functions available in some |
| 164 |
// versions of libc and not others. |
| 165 |
#[cfg(any( |
| 166 |
all(linux_raw, feature = "use-libc-auxv"), |
| 167 |
all(libc, not(any(windows, target_os = "espidf", target_os = "wasi"))) |
| 168 |
))] |
| 169 |
#[macro_use] |
| 170 |
mod weak; |
| 171 |
|
| 172 |
// Pick the backend implementation to use. |
| 173 |
#[cfg_attr(libc, path = "backend/libc/mod.rs")] |
| 174 |
#[cfg_attr(linux_raw, path = "backend/linux_raw/mod.rs")] |
| 175 |
#[cfg_attr(wasi, path = "backend/wasi/mod.rs")] |
| 176 |
mod backend; |
| 177 |
|
| 178 |
/// Export the `*Fd` types and traits that are used in rustix's public API. |
| 179 |
/// |
| 180 |
/// Users can use this to avoid needing to import anything else to use the same |
| 181 |
/// versions of these types and traits. |
| 182 |
pub mod fd { |
| 183 |
use super::backend; |
| 184 |
|
| 185 |
// Re-export `AsSocket` etc. too, as users can't implement `AsFd` etc. on |
| 186 |
// Windows due to them having blanket impls on Windows, so users must |
| 187 |
// implement `AsSocket` etc. |
| 188 |
#[cfg(windows)] |
| 189 |
pub use backend::fd::{AsRawSocket, AsSocket, FromRawSocket, IntoRawSocket}; |
| 190 |
|
| 191 |
pub use backend::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; |
| 192 |
} |
| 193 |
|
| 194 |
// The public API modules. |
| 195 |
#[cfg(feature = "event")] |
| 196 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "event")))] |
| 197 |
pub mod event; |
| 198 |
#[cfg(not(windows))] |
| 199 |
pub mod ffi; |
| 200 |
#[cfg(not(windows))] |
| 201 |
#[cfg(feature = "fs")] |
| 202 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "fs")))] |
| 203 |
pub mod fs; |
| 204 |
pub mod io; |
| 205 |
#[cfg(linux_kernel)] |
| 206 |
#[cfg(feature = "io_uring")] |
| 207 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "io_uring")))] |
| 208 |
pub mod io_uring; |
| 209 |
pub mod ioctl; |
| 210 |
#[cfg(not(any(windows, target_os = "espidf", target_os = "vita", target_os = "wasi")))] |
| 211 |
#[cfg(feature = "mm")] |
| 212 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "mm")))] |
| 213 |
pub mod mm; |
| 214 |
#[cfg(linux_kernel)] |
| 215 |
#[cfg(feature = "mount")] |
| 216 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "mount")))] |
| 217 |
pub mod mount; |
| 218 |
#[cfg(not(any(target_os = "redox", target_os = "wasi")))] |
| 219 |
#[cfg(feature = "net")] |
| 220 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "net")))] |
| 221 |
pub mod net; |
| 222 |
#[cfg(not(any(windows, target_os = "espidf")))] |
| 223 |
#[cfg(feature = "param")] |
| 224 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "param")))] |
| 225 |
pub mod param; |
| 226 |
#[cfg(not(windows))] |
| 227 |
#[cfg(any(feature = "fs", feature = "mount", feature = "net"))] |
| 228 |
#[cfg_attr( |
| 229 |
doc_cfg, |
| 230 |
doc(cfg(any(feature = "fs", feature = "mount", feature = "net"))) |
| 231 |
)] |
| 232 |
pub mod path; |
| 233 |
#[cfg(feature = "pipe")] |
| 234 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "pipe")))] |
| 235 |
#[cfg(not(any(windows, target_os = "wasi")))] |
| 236 |
pub mod pipe; |
| 237 |
#[cfg(not(windows))] |
| 238 |
#[cfg(feature = "process")] |
| 239 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "process")))] |
| 240 |
pub mod process; |
| 241 |
#[cfg(feature = "procfs")] |
| 242 |
#[cfg(linux_kernel)] |
| 243 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "procfs")))] |
| 244 |
pub mod procfs; |
| 245 |
#[cfg(not(windows))] |
| 246 |
#[cfg(not(target_os = "wasi"))] |
| 247 |
#[cfg(feature = "pty")] |
| 248 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "pty")))] |
| 249 |
pub mod pty; |
| 250 |
#[cfg(not(windows))] |
| 251 |
#[cfg(feature = "rand")] |
| 252 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "rand")))] |
| 253 |
pub mod rand; |
| 254 |
#[cfg(not(any( |
| 255 |
windows, |
| 256 |
target_os = "android", |
| 257 |
target_os = "espidf", |
| 258 |
target_os = "vita", |
| 259 |
target_os = "wasi" |
| 260 |
)))] |
| 261 |
#[cfg(feature = "shm")] |
| 262 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "shm")))] |
| 263 |
pub mod shm; |
| 264 |
#[cfg(not(windows))] |
| 265 |
#[cfg(feature = "stdio")] |
| 266 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "stdio")))] |
| 267 |
pub mod stdio; |
| 268 |
#[cfg(feature = "system")] |
| 269 |
#[cfg(not(any(windows, target_os = "wasi")))] |
| 270 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "system")))] |
| 271 |
pub mod system; |
| 272 |
#[cfg(not(any(windows, target_os = "vita")))] |
| 273 |
#[cfg(feature = "termios")] |
| 274 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "termios")))] |
| 275 |
pub mod termios; |
| 276 |
#[cfg(not(windows))] |
| 277 |
#[cfg(feature = "thread")] |
| 278 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "thread")))] |
| 279 |
pub mod thread; |
| 280 |
#[cfg(not(any(windows, target_os = "espidf")))] |
| 281 |
#[cfg(feature = "time")] |
| 282 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "time")))] |
| 283 |
pub mod time; |
| 284 |
|
| 285 |
// "runtime" is also a public API module, but it's only for libc-like users. |
| 286 |
#[cfg(not(windows))] |
| 287 |
#[cfg(feature = "runtime")] |
| 288 |
#[cfg(linux_raw)] |
| 289 |
#[cfg_attr(not(document_experimental_runtime_api), doc(hidden))] |
| 290 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "runtime")))] |
| 291 |
pub mod runtime; |
| 292 |
|
| 293 |
// Temporarily provide some mount functions for use in the fs module for |
| 294 |
// backwards compatibility. |
| 295 |
#[cfg(linux_kernel)] |
| 296 |
#[cfg(all(feature = "fs", not(feature = "mount")))] |
| 297 |
pub(crate) mod mount; |
| 298 |
|
| 299 |
// Declare "fs" as a non-public module if "fs" isn't enabled but we need it for |
| 300 |
// reading procfs. |
| 301 |
#[cfg(not(windows))] |
| 302 |
#[cfg(not(feature = "fs"))] |
| 303 |
#[cfg(all( |
| 304 |
linux_raw, |
| 305 |
not(feature = "use-libc-auxv"), |
| 306 |
not(feature = "use-explicitly-provided-auxv"), |
| 307 |
any( |
| 308 |
feature = "param", |
| 309 |
feature = "process", |
| 310 |
feature = "runtime", |
| 311 |
feature = "time", |
| 312 |
target_arch = "x86", |
| 313 |
) |
| 314 |
))] |
| 315 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "fs")))] |
| 316 |
pub(crate) mod fs; |
| 317 |
|
| 318 |
// Similarly, declare `path` as a non-public module if needed. |
| 319 |
#[cfg(not(windows))] |
| 320 |
#[cfg(not(any(feature = "fs", feature = "mount", feature = "net")))] |
| 321 |
#[cfg(all( |
| 322 |
linux_raw, |
| 323 |
not(feature = "use-libc-auxv"), |
| 324 |
not(feature = "use-explicitly-provided-auxv"), |
| 325 |
any( |
| 326 |
feature = "param", |
| 327 |
feature = "process", |
| 328 |
feature = "runtime", |
| 329 |
feature = "time", |
| 330 |
target_arch = "x86", |
| 331 |
) |
| 332 |
))] |
| 333 |
pub(crate) mod path; |
| 334 |
|
| 335 |
// Private modules used by multiple public modules. |
| 336 |
#[cfg(not(any(windows, target_os = "espidf")))] |
| 337 |
#[cfg(any(feature = "thread", feature = "time", target_arch = "x86"))] |
| 338 |
mod clockid; |
| 339 |
#[cfg(not(any(windows, target_os = "wasi")))] |
| 340 |
#[cfg(any( |
| 341 |
feature = "procfs", |
| 342 |
feature = "process", |
| 343 |
feature = "runtime", |
| 344 |
feature = "termios", |
| 345 |
feature = "thread", |
| 346 |
all(bsd, feature = "event"), |
| 347 |
all(linux_kernel, feature = "net") |
| 348 |
))] |
| 349 |
mod pid; |
| 350 |
#[cfg(any(feature = "process", feature = "thread"))] |
| 351 |
#[cfg(linux_kernel)] |
| 352 |
mod prctl; |
| 353 |
#[cfg(not(any(windows, target_os = "espidf", target_os = "wasi")))] |
| 354 |
#[cfg(any(feature = "process", feature = "runtime", all(bsd, feature = "event")))] |
| 355 |
mod signal; |
| 356 |
#[cfg(not(windows))] |
| 357 |
#[cfg(any( |
| 358 |
feature = "fs", |
| 359 |
feature = "process", |
| 360 |
feature = "runtime", |
| 361 |
feature = "thread", |
| 362 |
feature = "time", |
| 363 |
all( |
| 364 |
linux_raw, |
| 365 |
not(feature = "use-libc-auxv"), |
| 366 |
not(feature = "use-explicitly-provided-auxv"), |
| 367 |
any( |
| 368 |
feature = "param", |
| 369 |
feature = "process", |
| 370 |
feature = "runtime", |
| 371 |
feature = "time", |
| 372 |
target_arch = "x86", |
| 373 |
) |
| 374 |
) |
| 375 |
))] |
| 376 |
mod timespec; |
| 377 |
#[cfg(not(any(windows, target_os = "wasi")))] |
| 378 |
#[cfg(any( |
| 379 |
feature = "fs", |
| 380 |
feature = "process", |
| 381 |
feature = "thread", |
| 382 |
all( |
| 383 |
linux_raw, |
| 384 |
not(feature = "use-libc-auxv"), |
| 385 |
not(feature = "use-explicitly-provided-auxv"), |
| 386 |
any( |
| 387 |
feature = "param", |
| 388 |
feature = "runtime", |
| 389 |
feature = "time", |
| 390 |
target_arch = "x86", |
| 391 |
) |
| 392 |
), |
| 393 |
all(linux_kernel, feature = "net") |
| 394 |
))] |
| 395 |
mod ugid; |