| 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 |
|
5161 |
| 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 |
43876 |
| 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. |
17819 |
| 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. |
17804 |
| 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. |
6663 |
| 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). |
11187 |