Name Description Size
backend
bitcast.rs The `bitcast` and `bitflags_bits` macros. 985
buffer.rs Utilities to help with buffering. 547
check_types.rs Macros for checking that types have the same layout as other types. 2913
clockid.rs 5171
cstr.rs 2432
event
ffi.rs Utilities related to FFI bindings. 473
fs
io
io_uring.rs Linux [io_uring]. This API is very low-level. The main adaptations it makes from the raw Linux io_uring API are the use of appropriately-sized `bitflags`, `enum`, `Result`, `OwnedFd`, `AsFd`, `RawFd`, and `*mut c_void` in place of plain integers. For a higher-level API built on top of this, see the [rustix-uring] crate. # Safety io_uring operates on raw pointers and raw file descriptors. Rustix does not attempt to provide a safe API for these, because the abstraction level is too low for this to be practical. Safety should be introduced in higher-level abstraction layers. # References - [Linux] - [io_uring header] [Linux]: https://man.archlinux.org/man/io_uring.7.en [io_uring]: https://en.wikipedia.org/wiki/Io_uring [io_uring header]: https://github.com/torvalds/linux/blob/master/include/uapi/linux/io_uring.h [rustix-uring]: https://crates.io/crates/rustix-uring 44349
ioctl
lib.rs `rustix` provides efficient memory-safe and [I/O-safe] wrappers to POSIX-like, Unix-like, Linux, and Winsock syscall-like APIs, with configurable backends. With rustix, you can write code like this: ``` # #[cfg(feature = "net")] # fn read(sock: std::net::TcpStream, buf: &mut [u8]) -> std::io::Result<()> { # use rustix::net::RecvFlags; let nread: usize = rustix::net::recv(&sock, buf, RecvFlags::PEEK)?; # let _ = nread; # Ok(()) # } ``` instead of like this: ``` # #[cfg(feature = "net")] # fn read(sock: std::net::TcpStream, buf: &mut [u8]) -> std::io::Result<()> { # #[cfg(unix)] # use std::os::unix::io::AsRawFd; # #[cfg(target_os = "wasi")] # use std::os::wasi::io::AsRawFd; # #[cfg(windows)] # use windows_sys::Win32::Networking::WinSock as libc; # #[cfg(windows)] # use std::os::windows::io::AsRawSocket; # const MSG_PEEK: i32 = libc::MSG_PEEK; let nread: usize = unsafe { #[cfg(any(unix, target_os = "wasi"))] let raw = sock.as_raw_fd(); #[cfg(windows)] let raw = sock.as_raw_socket(); match libc::recv( raw as _, buf.as_mut_ptr().cast(), buf.len().try_into().unwrap_or(i32::MAX as _), MSG_PEEK, ) { -1 => return Err(std::io::Error::last_os_error()), nread => nread as usize, } }; # let _ = nread; # Ok(()) # } ``` rustix's APIs perform the following tasks: - Error values are translated to [`Result`]s. - Buffers are passed as Rust slices. - Out-parameters are presented as return values. - Path arguments use [`Arg`], so they accept any string type. - File descriptors are passed and returned via [`AsFd`] and [`OwnedFd`] instead of bare integers, ensuring I/O safety. - Constants use `enum`s and [`bitflags`] types, and enable [support for externally defined flags]. - Multiplexed functions (eg. `fcntl`, `ioctl`, etc.) are de-multiplexed. - Variadic functions (eg. `openat`, etc.) are presented as non-variadic. - Functions that return strings automatically allocate sufficient memory and retry the syscall as needed to determine the needed length. - Functions and types which need `l` prefixes or `64` suffixes to enable large-file support (LFS) are used automatically. File sizes and offsets are always presented as `u64` and `i64`. - Behaviors that depend on the sizes of C types like `long` are hidden. - In some places, more human-friendly and less historical-accident names are used (and documentation aliases are used so that the original names can still be searched for). - Provide y2038 compatibility, on platforms which support this. - Correct selected platform bugs, such as behavioral differences when running under seccomp. Things they don't do include: - Detecting whether functions are supported at runtime, except in specific cases where new interfaces need to be detected to support y2038 and LFS. - Hiding significant differences between platforms. - Restricting ambient authorities. - Imposing sandboxing features such as filesystem path or network address sandboxing. See [`cap-std`], [`system-interface`], and [`io-streams`] for libraries which do hide significant differences between platforms, and [`cap-std`] which does perform sandboxing and restricts ambient authorities. [`cap-std`]: https://crates.io/crates/cap-std [`system-interface`]: https://crates.io/crates/system-interface [`io-streams`]: https://crates.io/crates/io-streams [`getrandom`]: https://crates.io/crates/getrandom [`bitflags`]: https://crates.io/crates/bitflags [`AsFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.AsFd.html [`OwnedFd`]: https://doc.rust-lang.org/stable/std/os/fd/struct.OwnedFd.html [I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md [`Result`]: https://doc.rust-lang.org/stable/std/result/enum.Result.html [`Arg`]: https://docs.rs/rustix/*/rustix/path/trait.Arg.html [support for externally defined flags]: https://docs.rs/bitflags/*/bitflags/#externally-defined-flags 13437
maybe_polyfill
mm
mount
net
param
path
pid.rs The `Pid` type. 3176
pipe.rs `pipe` and related APIs. # Safety `vmsplice` is an unsafe function. 6507
prctl.rs Helper functions for `prctl` syscalls. 2361
process
procfs.rs Utilities for working with `/proc`, where Linux's `procfs` is typically mounted. `/proc` serves as an adjunct to Linux's main syscall surface area, providing additional features with an awkward interface. This module does a considerable amount of work to determine whether `/proc` is mounted, with actual `procfs`, and without any additional mount points on top of the paths we open. Why all the effort to detect bind mount points? People are doing all kinds of things with Linux containers these days, with many different privilege schemes, and we want to avoid making any unnecessary assumptions. Rustix and its users will sometimes use procfs *implicitly* (when Linux gives them no better options), in ways that aren't obvious from their public APIs. These filesystem accesses might not be visible to someone auditing the main code of an application for places which may be influenced by the filesystem namespace. So with the checking here, they may fail, but they won't be able to succeed with bogus results. 17926
pty.rs Pseudoterminal operations. For the `openpty` and `login_tty` functions, see the [rustix-openpty crate]. [rustix-openpty crate]: https://crates.io/crates/rustix-openpty 6790
rand
runtime.rs Experimental low-level implementation details for libc-like runtime libraries such as [Origin]. Do not use the functions in this module unless you've read all of their code. They don't always behave the same way as functions with similar names in `libc`. Sometimes information about the differences is included in the Linux documentation under “C library/kernel differences” sections. And, if there is a libc in the process, these functions may have surprising interactions with it. These functions are for implementing thread-local storage (TLS), managing threads, loaded libraries, and other process-wide resources. Most of `rustix` doesn't care about what other libraries are linked into the program or what they're doing, but the features in this module generally can only be used by one entity within a process. The API for these functions is not stable, and this module is `doc(hidden)`. [Origin]: https://github.com/sunfishcode/origin#readme # Safety This module is intended to be used for implementing a runtime library such as libc. Use of these features for any other purpose is likely to create serious problems. 19244
shm.rs POSIX shared memory 1353
signal.rs 7646
static_assertions.rs Workarounds for Rust 1.63 where some things in the `static_assertions` crate do things that don't work in const contexts. We want to call them in const contexts in Rust versions where that's supported so that problems are caught at compile time, and fall back to dynamic asserts in Rust 1.63. 890
stdio.rs Functions returning the stdio file descriptors. # Safety These access the file descriptors by absolute index value, and nothing prevents them from being closed and reused. They should only be used in `main` or other situations where one is in control of the process' stdio streams. 17802
system.rs Uname and other system-level functions. # Safety This function converts from `struct utsname` fields provided from the kernel into `&str` references, which assumes that they're NUL-terminated. 7751
termios
thread
time
timespec.rs `Timespec` and related types, which are used by multiple public API modules. 2781
ugid.rs User and Group ID types. 2299
utils.rs Miscellaneous minor utilities. 2179
weak.rs Support for "weak linkage" to symbols on Unix Some I/O operations we do in libstd require newer versions of OSes but we need to maintain binary compatibility with older releases for now. In order to use the new functionality when available we use this module for detection. One option to use here is weak linkage, but that is unfortunately only really workable on Linux. Hence, use dlsym to get the symbol value at runtime. This is also done for compatibility with older versions of glibc, and to avoid creating dependencies on `GLIBC_PRIVATE` symbols. It assumes that we've been dynamically linked to the library the symbol comes from, but that is currently always the case for things like libpthread/libc. A long time ago this used weak linkage for the `__pthread_get_minstack` symbol, but that caused Debian to detect an unnecessarily strict versioned dependency on libc6 (#23628). 11219