| backend |
|
|
- |
| bitcast.rs |
The `bitcast` and `bitflags_bits` macros. |
1102 |
- |
| buffer.rs |
Utilities for functions that return data via buffers. |
15460 |
- |
| check_types.rs |
Macros for checking that types have the same layout as other types. |
4352 |
- |
| clockid.rs |
|
7813 |
- |
| cstr.rs |
|
3443 |
- |
| event |
|
|
- |
| ffi.rs |
Utilities related to FFI bindings. |
789 |
- |
| fs |
|
|
- |
| io |
|
|
- |
| io_uring |
|
|
- |
| ioctl |
|
|
- |
| kernel_sigset.rs |
The [`KernelSigSet`] type. |
9610 |
- |
| 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, _received) = 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 = 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.
- Use `timespec` for timestamps and timeouts instead of `timeval` and
`c_int` milliseconds.
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
[`bitflags`]: bitflags
[`AsFd`]: crate::fd::AsFd
[`OwnedFd`]: crate::fd::OwnedFd
[I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md
[`Arg`]: path::Arg
[support for externally defined flags]: bitflags#externally-defined-flags |
14211 |
- |
| maybe_polyfill |
|
|
- |
| mm |
|
|
- |
| mount |
|
|
- |
| msan.rs |
|
406 |
- |
| net |
|
|
- |
| not_implemented.rs |
Documentation about unimplemented functions.
This module contains documentation for several functions that rustix does
not implement, either because they are out of scope, or because they are
could probably be implemented but are not yet. |
13909 |
- |
| param |
|
|
- |
| path |
|
|
- |
| pid.rs |
The `Pid` type. |
5260 |
- |
| pipe.rs |
`pipe` and related APIs. |
6645 |
- |
| prctl.rs |
Helper functions for `prctl` syscalls. |
2375 |
- |
| process |
|
|
- |
| 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 |
6954 |
- |
| rand |
|
|
- |
| runtime.rs |
Experimental low-level implementation details for libc-like runtime
libraries such as [Origin].
⚠ These are not normal functions. ⚠
- Some of the functions in this module cannot be used in a process which
also has a libc present. This can be true even for functions that have
the same name as a libc function that Rust code can use. Such functions
are not marked `unsafe` (unless they are unsafe for other reasons), even
though they invoke Undefined Behavior if called in a process which has a
libc present.
- Some of the functions in this module don't behave exactly the same way
as functions in libc with similar names. Sometimes information about the
differences is included in the Linux documentation under “C
library/kernel differences” sections. But not always.
- The safety requirements of the functions in this module are not fully
documented.
- The API for these functions is not considered stable, and this module is
`doc(hidden)`.
⚠ Caution is indicated. ⚠
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.
All that said, there are some functions in this module would could
potentially be stabilized and moved to other modules. See also the
documentation for specific functions in the [`not_implemented`] module, and
the discussion in [#1314].
[Origin]: https://github.com/sunfishcode/origin#readme
[`not_implemented`]: crate::not_implemented
[#1314]: https://github.com/bytecodealliance/rustix/issues/1314
# 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. |
33233 |
- |
| shm.rs |
POSIX shared memory
# Examples
```
use rustix::fs::{ftruncate, Mode};
use rustix::mm::{mmap, MapFlags, ProtFlags};
use rustix::{io, shm};
use std::mem::size_of;
use std::ptr::null_mut;
# fn example() -> io::Result<()> {
// A type describing the data to be shared.
#[repr(C)]
struct MyBufferType {
// …
}
// Create the shared memory object.
let shm_path = "/rustix-shm-example";
let fd = shm::open(
shm_path,
shm::OFlags::CREATE | shm::OFlags::EXCL | shm::OFlags::RDWR,
Mode::RUSR | Mode::WUSR,
)?;
// Resize the shared memory object to the size of our data.
ftruncate(&fd, size_of::<MyBufferType>() as u64)?;
// Map the shared memory object into our address space.
//
// SAFETY: We're creating a new mapping that's independent of any existing
// memory allocations. There are interesting things to say about *using*
// `ptr`, but that's for another safety comment.
let ptr = unsafe {
mmap(
null_mut(),
size_of::<MyBufferType>(),
ProtFlags::READ | ProtFlags::WRITE,
MapFlags::SHARED,
&fd,
0,
)?
};
// Use `ptr`…
// Remove the shared memory object name.
shm::unlink(shm_path)?;
# Ok(())
# }
``` |
2820 |
- |
| signal.rs |
Signal numbers.
# Safety
Some signal numbers are reserved by the libc.
[`Signal::from_raw_unchecked`] and [`Signal::from_raw_nonzero_unchecked`]
allow constructing `Signal` values with arbitrary values. Users must avoid
using reserved values to send, consume, or block any signals or alter any
signal handlers.
See the individual functions' safety comments for more details. |
21364 |
- |
| 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
Some of the functions in this module can cause the process' stdio file
descriptors to be closed, which breaks the assumption made in Rust's std
that these file descriptors are always open.
And in no-std mode, some of the functions in this module similarly assume
that the process' stdio file descriptors are open, which we don't take as
given in no-std mode because we don't have std also making that assumption.
See the individual functions' safety comments for more details. |
18399 |
- |
| system.rs |
Uname and other system-level functions. |
9682 |
- |
| termios |
|
|
- |
| thread |
|
|
- |
| time |
|
|
- |
| timespec.rs |
`Timespec` and related types, which are used by multiple public API
modules. |
11411 |
- |
| ugid.rs |
User and Group ID types. |
4621 |
- |
| utils.rs |
Miscellaneous minor utilities. |
1990 |
- |
| 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). |
11274 |
- |