From 8c96f2091b7399eaa9ac71945eada5b78d616586 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Sat, 15 Feb 2025 19:22:54 -0800 Subject: [PATCH] Miscellaneous documentaion cleanups. - Update documentation links to Linux 6.13. - Use shorter forms of docs.rs links. - Fix typos in comments. - Update some maybe_polyfill comments to match upstream. - Comment formatting. - Update io_uring documentation links to point to man7.org. - Add some useful docs. - Tidying the not_implmented docs. - Fix a doc link in CHANGES.md. - Add doc aliases. --- CHANGES.md | 4 +- src/backend/libc/c.rs | 2 +- src/backend/libc/event/syscalls.rs | 2 +- src/backend/libc/fs/dir.rs | 4 +- src/backend/libc/fs/syscalls.rs | 6 +- src/backend/libc/net/addr.rs | 7 ++- src/backend/linux_raw/fs/dir.rs | 4 +- src/backend/linux_raw/fs/syscalls.rs | 2 +- src/backend/linux_raw/fs/types.rs | 16 +++--- src/backend/linux_raw/io/errno.rs | 2 +- src/backend/linux_raw/io/syscalls.rs | 4 +- src/backend/linux_raw/net/addr.rs | 7 ++- src/backend/linux_raw/vdso.rs | 2 +- src/event/select.rs | 3 +- src/fs/fd.rs | 2 +- src/io_uring/mod.rs | 12 ++-- src/lib.rs | 1 + src/maybe_polyfill/no_std/os/fd/owned.rs | 15 +++-- .../no_std/os/windows/io/raw.rs | 3 +- .../no_std/os/windows/io/socket.rs | 2 +- src/maybe_polyfill/std/mod.rs | 2 +- src/net/addr.rs | 21 +++---- src/net/send_recv/msg.rs | 12 ++-- src/net/socket_addr_any.rs | 17 +++--- src/net/types.rs | 16 +++--- src/not_implemented.rs | 8 +-- src/pipe.rs | 4 -- src/prctl.rs | 2 +- src/process/pidfd.rs | 2 +- src/process/prctl.rs | 8 +-- src/process/procctl.rs | 10 ++-- src/runtime.rs | 2 +- src/signal.rs | 56 ++++++++++++------- src/stdio.rs | 37 ++++++------ src/system.rs | 6 +- src/termios/ioctl.rs | 2 +- src/thread/prctl.rs | 14 ++--- src/thread/setns.rs | 20 +++---- tests/net/sockopt.rs | 22 ++++---- 39 files changed, 193 insertions(+), 168 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 5fbb470b4..c9be7227b 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -46,7 +46,7 @@ constant. `rustix::process::WaitidOptions` and `rustix::process::WaitidStatus` are renamed to [`rustix::process::WaitIdOptions`] and [`rustix::process::WaitIdStatus`] (note -the capitalization), for consistency with [`crate::process::WaitId`]. +the capitalization), for consistency with [`rustix::process::WaitId`]. [`rustix::process::WaitIdOptions`]: https://docs.rs/rustix/1.0.0/rustix/process/struct.WaitIdOptions.html [`rustix::process::WaitIdStatus`]: https://docs.rs/rustix/1.0.0/rustix/process/struct.WaitIdStatus.html @@ -198,7 +198,7 @@ be used in place of `mount2`, and `mount2` is now removed. The [`rustix::net`] functions ending with `_v4`, `_v6`, `_unix` and `_xdp` have been merged into a single function that accepts any address type. -Specically, the following functions are removed: +Specifically, the following functions are removed: * `bind_any`, `bind_unix`, `bind_v4`, `bind_v6`, `bind_xdp` in favor of [`bind`], diff --git a/src/backend/libc/c.rs b/src/backend/libc/c.rs index 442f88a79..147b60248 100644 --- a/src/backend/libc/c.rs +++ b/src/backend/libc/c.rs @@ -87,7 +87,7 @@ pub(crate) const XCASE: tcflag_t = linux_raw_sys::general::XCASE as _; pub(crate) const MSG_DONTWAIT: c_int = MSG_NONBLOCK; // `O_LARGEFILE` can be automatically set by the kernel on Linux: -// +// // so libc implementations may leave it undefined or defined to zero. #[cfg(linux_kernel)] pub(crate) const O_LARGEFILE: c_int = linux_raw_sys::general::O_LARGEFILE as _; diff --git a/src/backend/libc/event/syscalls.rs b/src/backend/libc/event/syscalls.rs index f180ec457..92ec2915f 100644 --- a/src/backend/libc/event/syscalls.rs +++ b/src/backend/libc/event/syscalls.rs @@ -575,7 +575,7 @@ pub(crate) fn epoll_wait( .map(|i| i as usize) } - // Othewise just use `epoll_wait`. + // Otherwise just use `epoll_wait`. #[cfg(not(all(linux_kernel, feature = "linux_5_11")))] unsafe { let timeout = match timeout { diff --git a/src/backend/libc/fs/dir.rs b/src/backend/libc/fs/dir.rs index 683575e72..277a4fcac 100644 --- a/src/backend/libc/fs/dir.rs +++ b/src/backend/libc/fs/dir.rs @@ -137,11 +137,11 @@ impl Dir { /// `seekdir(self, offset)` /// - /// This function iso only available on 64-bit platforms because it's + /// This function is only available on 64-bit platforms because it's /// implemented using [`libc::seekdir`] which only supports offsets that /// fit in a `c_long`. /// - /// [`libc::seekdir`]: https://docs.rs/libc/latest/arm-unknown-linux-gnueabihf/libc/fn.seekdir.html + /// [`libc::seekdir`]: https://docs.rs/libc/*/arm-unknown-linux-gnueabihf/libc/fn.seekdir.html #[cfg(target_pointer_width = "64")] #[cfg_attr(docsrs, doc(cfg(target_pointer_width = "64")))] #[doc(alias = "seekdir")] diff --git a/src/backend/libc/fs/syscalls.rs b/src/backend/libc/fs/syscalls.rs index 74108a7bb..95625fe75 100644 --- a/src/backend/libc/fs/syscalls.rs +++ b/src/backend/libc/fs/syscalls.rs @@ -1251,9 +1251,9 @@ pub(crate) fn fadvise( } } - // Similarly, on FreeBSD, if `offset + len` would overflow an `off_t` in - // a way that users using a `u64` interface wouldn't be aware of, reduce - // the length so that we only operate on the range that doesn't overflow. + // Similarly, on FreeBSD, if `offset + len` would overflow an `off_t` in a + // way that users using a `u64` interface wouldn't be aware of, reduce the + // length so that we only operate on the range that doesn't overflow. #[cfg(target_os = "freebsd")] let len = if len > 0 && offset.checked_add(len).is_none() { i64::MAX - offset diff --git a/src/backend/libc/net/addr.rs b/src/backend/libc/net/addr.rs index ea4f24918..5caa489a8 100644 --- a/src/backend/libc/net/addr.rs +++ b/src/backend/libc/net/addr.rs @@ -236,17 +236,18 @@ impl fmt::Debug for SocketAddrUnix { } } -/// `struct sockaddr_storage`. +/// `struct sockaddr_storage` /// /// This type is guaranteed to be large enough to hold any encoded socket /// address. #[repr(transparent)] #[derive(Copy, Clone)] +#[doc(alias = "sockaddr_storage")] pub struct SocketAddrStorage(c::sockaddr_storage); impl SocketAddrStorage { /// Return a socket addr storage initialized to all zero bytes. The - /// `sa_family` is set to `AddressFamily::UNSPEC`. + /// `sa_family` is set to [`AddressFamily::UNSPEC`]. pub fn zeroed() -> Self { assert_eq!(c::AF_UNSPEC, 0); // SAFETY: `sockaddr_storage` is meant to be zero-initializable. @@ -264,7 +265,7 @@ impl SocketAddrStorage { } /// Clear the `sa_family` of this socket address to - /// `AddressFamily::UNSPEC`. + /// [`AddressFamily::UNSPEC`]. pub fn clear_family(&mut self) { // SAFETY: `self.0` is a `sockaddr_storage` so it has enough space. unsafe { diff --git a/src/backend/linux_raw/fs/dir.rs b/src/backend/linux_raw/fs/dir.rs index 5423fa4bb..c0241b3e5 100644 --- a/src/backend/linux_raw/fs/dir.rs +++ b/src/backend/linux_raw/fs/dir.rs @@ -81,11 +81,11 @@ impl Dir { /// `seekdir(self, offset)` /// - /// This function iso only available on 64-bit platforms because it's + /// This function is only available on 64-bit platforms because it's /// implemented using [`libc::seekdir`] which only supports offsets that /// fit in a `c_long`. /// - /// [`libc::seekdir`]: https://docs.rs/libc/latest/arm-unknown-linux-gnueabihf/libc/fn.seekdir.html + /// [`libc::seekdir`]: https://docs.rs/libc/*/arm-unknown-linux-gnueabihf/libc/fn.seekdir.html // In the linux_raw backend here, we don't use `libc::seekdir` and don't // have this limitation, but it's a goal of rustix to support the same API // on both the linux_raw and libc backends. diff --git a/src/backend/linux_raw/fs/syscalls.rs b/src/backend/linux_raw/fs/syscalls.rs index 7dd19ab09..5d0554ec2 100644 --- a/src/backend/linux_raw/fs/syscalls.rs +++ b/src/backend/linux_raw/fs/syscalls.rs @@ -287,7 +287,7 @@ pub(crate) fn tell(fd: BorrowedFd<'_>) -> io::Result { #[inline] pub(crate) fn ftruncate(fd: BorrowedFd<'_>, length: u64) -> io::Result<()> { - // + // #[cfg(all( target_pointer_width = "32", any( diff --git a/src/backend/linux_raw/fs/types.rs b/src/backend/linux_raw/fs/types.rs index 334c8a5bd..ce6461c3d 100644 --- a/src/backend/linux_raw/fs/types.rs +++ b/src/backend/linux_raw/fs/types.rs @@ -197,13 +197,13 @@ bitflags! { /// `O_DIRECTORY` const DIRECTORY = linux_raw_sys::general::O_DIRECTORY; - /// `O_DSYNC`. + /// `O_DSYNC` const DSYNC = linux_raw_sys::general::O_SYNC; /// `O_EXCL` const EXCL = linux_raw_sys::general::O_EXCL; - /// `O_FSYNC`. + /// `O_FSYNC` const FSYNC = linux_raw_sys::general::O_SYNC; /// `O_NOFOLLOW` @@ -226,7 +226,7 @@ bitflags! { /// `O_NOCTTY` const NOCTTY = linux_raw_sys::general::O_NOCTTY; - /// `O_RSYNC`. + /// `O_RSYNC` const RSYNC = linux_raw_sys::general::O_SYNC; /// `O_SYNC` @@ -252,7 +252,7 @@ bitflags! { /// `O_LARGEFILE` /// - /// Tustix and/or libc will automatically set this flag when + /// Rustix and/or libc will automatically set this flag when /// appropriate in the [`rustix::fs::open`] family of functions, so /// typical users do not need to care about it. It may be reported in /// the return of `fcntl_getfl`, though. @@ -486,13 +486,13 @@ bitflags! { #[repr(transparent)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct SealFlags: u32 { - /// `F_SEAL_SEAL`. + /// `F_SEAL_SEAL` const SEAL = linux_raw_sys::general::F_SEAL_SEAL; - /// `F_SEAL_SHRINK`. + /// `F_SEAL_SHRINK` const SHRINK = linux_raw_sys::general::F_SEAL_SHRINK; - /// `F_SEAL_GROW`. + /// `F_SEAL_GROW` const GROW = linux_raw_sys::general::F_SEAL_GROW; - /// `F_SEAL_WRITE`. + /// `F_SEAL_WRITE` const WRITE = linux_raw_sys::general::F_SEAL_WRITE; /// `F_SEAL_FUTURE_WRITE` (since Linux 5.1) const FUTURE_WRITE = linux_raw_sys::general::F_SEAL_FUTURE_WRITE; diff --git a/src/backend/linux_raw/io/errno.rs b/src/backend/linux_raw/io/errno.rs index 9dd67a8a8..4ddf6df5f 100644 --- a/src/backend/linux_raw/io/errno.rs +++ b/src/backend/linux_raw/io/errno.rs @@ -349,7 +349,7 @@ impl Errno { pub const ILSEQ: Self = Self::from_errno(errno::EILSEQ); /// `EINPROGRESS` pub const INPROGRESS: Self = Self::from_errno(errno::EINPROGRESS); - /// `EINTR`. + /// `EINTR` /// /// For a convenient way to retry system calls that exit with `INTR`, use /// [`retry_on_intr`]. diff --git a/src/backend/linux_raw/io/syscalls.rs b/src/backend/linux_raw/io/syscalls.rs index 334886ccd..163090a26 100644 --- a/src/backend/linux_raw/io/syscalls.rs +++ b/src/backend/linux_raw/io/syscalls.rs @@ -38,7 +38,7 @@ pub(crate) unsafe fn pread( len: usize, pos: u64, ) -> io::Result { - // + // #[cfg(all( target_pointer_width = "32", any(target_arch = "arm", target_arch = "mips", target_arch = "mips32r6"), @@ -142,7 +142,7 @@ pub(crate) fn write(fd: BorrowedFd<'_>, buf: &[u8]) -> io::Result { pub(crate) fn pwrite(fd: BorrowedFd<'_>, buf: &[u8], pos: u64) -> io::Result { let (buf_addr, buf_len) = slice(buf); - // + // #[cfg(all( target_pointer_width = "32", any(target_arch = "arm", target_arch = "mips", target_arch = "mips32r6"), diff --git a/src/backend/linux_raw/net/addr.rs b/src/backend/linux_raw/net/addr.rs index 156c4f791..d389d1cd7 100644 --- a/src/backend/linux_raw/net/addr.rs +++ b/src/backend/linux_raw/net/addr.rs @@ -187,12 +187,13 @@ impl fmt::Debug for SocketAddrUnix { } } -/// `struct sockaddr_storage`. +/// `struct sockaddr_storage` /// /// This type is guaranteed to be large enough to hold any encoded socket /// address. #[repr(transparent)] #[derive(Copy, Clone)] +#[doc(alias = "sockaddr_storage")] pub struct SocketAddrStorage(c::sockaddr_storage); // SAFETY: Bindgen adds a union with a raw pointer for alignment but it's never @@ -205,7 +206,7 @@ unsafe impl Sync for SocketAddrStorage {} impl SocketAddrStorage { /// Return a socket addr storage initialized to all zero bytes. The - /// `sa_family` is set to `AddressFamily::UNSPEC`. + /// `sa_family` is set to [`AddressFamily::UNSPEC`]. pub fn zeroed() -> Self { assert_eq!(c::AF_UNSPEC, 0); // SAFETY: `sockaddr_storage` is meant to be zero-initializable. @@ -223,7 +224,7 @@ impl SocketAddrStorage { } /// Clear the `sa_family` of this socket address to - /// `AddressFamily::UNSPEC`. + /// [`AddressFamily::UNSPEC`]. pub fn clear_family(&mut self) { // SAFETY: `self.0` is a `sockaddr_storage` so it has enough space. unsafe { diff --git a/src/backend/linux_raw/vdso.rs b/src/backend/linux_raw/vdso.rs index 76a7f67b4..1e74c99d0 100644 --- a/src/backend/linux_raw/vdso.rs +++ b/src/backend/linux_raw/vdso.rs @@ -1,7 +1,7 @@ //! Parse the Linux vDSO. //! //! The following code is transliterated from -//! tools/testing/selftests/vDSO/parse_vdso.c in Linux 6.12, which is licensed +//! tools/testing/selftests/vDSO/parse_vdso.c in Linux 6.13, which is licensed //! with Creative Commons Zero License, version 1.0, //! available at //! diff --git a/src/event/select.rs b/src/event/select.rs index fd7e73f4d..e7660479a 100644 --- a/src/event/select.rs +++ b/src/event/select.rs @@ -180,8 +180,7 @@ pub fn fd_set_remove(fds: &mut [FdSetElement], fd: RawFd) { } } -/// Compute the minimum `nfds` value needed for the set pointed to by -/// `fds`. +/// Compute the minimum `nfds` value needed for the set pointed to by `fds`. #[inline] pub fn fd_set_bound(fds: &[FdSetElement]) -> RawFd { #[cfg(not(any(windows, target_os = "wasi")))] diff --git a/src/fs/fd.rs b/src/fs/fd.rs index 79f3e2472..9cd8028b2 100644 --- a/src/fs/fd.rs +++ b/src/fs/fd.rs @@ -246,7 +246,7 @@ pub fn futimens(fd: Fd, times: &Timestamps) -> io::Result<()> { target_os = "nto", target_os = "redox", target_os = "vita", -)))] // not implemented in libc for netbsd yet +)))] // not implemented in libc for NetBSD yet #[inline] #[doc(alias = "posix_fallocate")] pub fn fallocate(fd: Fd, mode: FallocateFlags, offset: u64, len: u64) -> io::Result<()> { diff --git a/src/io_uring/mod.rs b/src/io_uring/mod.rs index 99e919b27..e57cf8930 100644 --- a/src/io_uring/mod.rs +++ b/src/io_uring/mod.rs @@ -18,9 +18,9 @@ //! - [Linux] //! - [io_uring header] //! -//! [Linux]: https://man.archlinux.org/man/io_uring.7.en +//! [Linux]: https://www.man7.org/linux/man-pages/man7/io_uring.7.html //! [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 +//! [io_uring header]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/io_uring.h?h=v6.13 //! [rustix-uring]: https://crates.io/crates/rustix-uring #![allow(unsafe_code)] @@ -68,7 +68,7 @@ mod sys { /// # References /// - [Linux] /// -/// [Linux]: https://man.archlinux.org/man/io_uring_setup.2.en +/// [Linux]: https://www.man7.org/linux/man-pages/man2/io_uring_setup.2.html #[inline] pub fn io_uring_setup(entries: u32, params: &mut io_uring_params) -> io::Result { backend::io_uring::syscalls::io_uring_setup(entries, params) @@ -88,7 +88,7 @@ pub fn io_uring_setup(entries: u32, params: &mut io_uring_params) -> io::Result< /// # References /// - [Linux] /// -/// [Linux]: https://man.archlinux.org/man/io_uring_register.2.en +/// [Linux]: https://www.man7.org/linux/man-pages/man2/io_uring_register.2.html #[inline] pub unsafe fn io_uring_register( fd: Fd, @@ -111,7 +111,7 @@ pub unsafe fn io_uring_register( /// # References /// - [Linux] /// -/// [Linux]: https://man.archlinux.org/man/io_uring_register.2.en +/// [Linux]: https://www.man7.org/linux/man-pages/man2/io_uring_register.2.html #[inline] pub unsafe fn io_uring_register_with( fd: Fd, @@ -135,7 +135,7 @@ pub unsafe fn io_uring_register_with( /// # References /// - [Linux] /// -/// [Linux]: https://man.archlinux.org/man/io_uring_enter.2.en +/// [Linux]: https://www.man7.org/linux/man-pages/man2/io_uring_enter.2.html #[inline] pub unsafe fn io_uring_enter( fd: Fd, diff --git a/src/lib.rs b/src/lib.rs index da0a3aa30..952b18b3e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -402,4 +402,5 @@ mod timespec; mod ugid; #[cfg(doc)] +#[cfg_attr(docsrs, doc(cfg(doc)))] pub mod not_implemented; diff --git a/src/maybe_polyfill/no_std/os/fd/owned.rs b/src/maybe_polyfill/no_std/os/fd/owned.rs index d765c1dd6..927d0e471 100644 --- a/src/maybe_polyfill/no_std/os/fd/owned.rs +++ b/src/maybe_polyfill/no_std/os/fd/owned.rs @@ -27,9 +27,14 @@ use core::mem::forget; /// passed as an argument, it is not captured or consumed, and it never has the /// value `-1`. /// -/// This type's `.to_owned()` implementation returns another `BorrowedFd` -/// rather than an `OwnedFd`. It just makes a trivial copy of the raw file -/// descriptor, which is then borrowed under the same lifetime. +/// This type does not have a [`ToOwned`][crate::borrow::ToOwned] +/// implementation. Calling `.to_owned()` on a variable of this type will call +/// it on `&BorrowedFd` and use `Clone::clone()` like `ToOwned` does for all +/// types implementing `Clone`. The result will be descriptor borrowed under +/// the same lifetime. +/// +/// To obtain an [`OwnedFd`], you can use [`BorrowedFd::try_clone_to_owned`] +/// instead, but this is not supported on all platforms. #[derive(Copy, Clone)] #[repr(transparent)] #[cfg_attr(rustc_attrs, rustc_layout_scalar_valid_range_start(0))] @@ -53,6 +58,8 @@ pub struct BorrowedFd<'fd> { /// descriptor, so it can be used in FFI in places where a file descriptor is /// passed as a consumed argument or returned as an owned value, and it never /// has the value `-1`. +/// +/// You can use [`AsFd::as_fd`] to obtain a [`BorrowedFd`]. #[repr(transparent)] #[cfg_attr(rustc_attrs, rustc_layout_scalar_valid_range_start(0))] // libstd/os/raw/mod.rs assures me that every libstd-supported platform has a @@ -66,7 +73,7 @@ pub struct OwnedFd { } impl BorrowedFd<'_> { - /// Return a `BorrowedFd` holding the given raw file descriptor. + /// Returns a `BorrowedFd` holding the given raw file descriptor. /// /// # Safety /// diff --git a/src/maybe_polyfill/no_std/os/windows/io/raw.rs b/src/maybe_polyfill/no_std/os/windows/io/raw.rs index 1e73e0019..63edf7f6d 100644 --- a/src/maybe_polyfill/no_std/os/windows/io/raw.rs +++ b/src/maybe_polyfill/no_std/os/windows/io/raw.rs @@ -45,10 +45,11 @@ pub trait FromRawSocket { /// # Safety /// /// The `socket` passed in must: - /// - be a valid an open socket, + /// - be an [owned socket][io-safety]; in particular, it must be open. /// - be a socket that may be freed via [`closesocket`]. /// /// [`closesocket`]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-closesocket + /// [io-safety]: io#io-safety #[cfg_attr(staged_api, stable(feature = "from_raw_os", since = "1.1.0"))] unsafe fn from_raw_socket(sock: RawSocket) -> Self; } diff --git a/src/maybe_polyfill/no_std/os/windows/io/socket.rs b/src/maybe_polyfill/no_std/os/windows/io/socket.rs index bc637aa53..d9514d238 100644 --- a/src/maybe_polyfill/no_std/os/windows/io/socket.rs +++ b/src/maybe_polyfill/no_std/os/windows/io/socket.rs @@ -70,7 +70,7 @@ pub struct OwnedSocket { } impl BorrowedSocket<'_> { - /// Return a `BorrowedSocket` holding the given raw socket. + /// Returns a `BorrowedSocket` holding the given raw socket. /// /// # Safety /// diff --git a/src/maybe_polyfill/std/mod.rs b/src/maybe_polyfill/std/mod.rs index c352a9ea2..17b280959 100644 --- a/src/maybe_polyfill/std/mod.rs +++ b/src/maybe_polyfill/std/mod.rs @@ -19,7 +19,7 @@ pub mod net { pub mod os { pub mod fd { - // Change to use `std::os::fd` when MSRV becomes 1.66 or higher. + // Change to use `std::os::fd` when MSRV becomes Rust 1.66 or higher. #[cfg(target_os = "wasi")] pub use std::os::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; diff --git a/src/net/addr.rs b/src/net/addr.rs index b5a68822c..2c5630692 100644 --- a/src/net/addr.rs +++ b/src/net/addr.rs @@ -21,8 +21,8 @@ use super::SocketAddrUnix; /// Opaque type equivalent to `sockaddr` in C. /// /// This is always used behind a raw pointer that is cast from a pointer to a -/// `sockaddr`-compatible C type, and then cast back to a `sockaddr` pointer -/// to be passed to a system call. +/// `sockaddr`-compatible C type, and then cast back to a `sockaddr` pointer to +/// be passed to a system call. #[repr(C)] pub struct SocketAddrOpaque { _data: [u8; 0], @@ -32,21 +32,22 @@ pub struct SocketAddrOpaque { /// /// This type will always be big enough to hold any socket address, but never /// bigger than `usize`. +#[doc(alias = "socklen_t")] pub type SocketAddrLen = u32; /// A trait abstracting over the types that can be passed as a `sockaddr`. /// /// # Safety /// -/// Implementers of this trait must ensure that `with_sockaddr` calls -/// `f` with a pointer that is readable for the passed length, and points -/// to data that is a valid socket address for the system calls that accept -/// `sockaddr` as a const pointer. +/// Implementers of this trait must ensure that `with_sockaddr` calls `f` with +/// a pointer that is readable for the passed length, and points to data that +/// is a valid socket address for the system calls that accept `sockaddr` as a +/// const pointer. pub unsafe trait SocketAddrArg { /// Call a closure with the pointer and length to the corresponding C type. /// - /// The memory pointed to by the pointer of size length is guaranteed to - /// be valid only for the duration of the call. + /// The memory pointed to by the pointer of size length is guaranteed to be + /// valid only for the duration of the call. /// /// The API uses a closure so that: /// * The libc types are not exposed in the rustix API. @@ -103,8 +104,8 @@ pub unsafe trait SocketAddrArg { /// # Safety /// /// This calls `f` with a pointer to an object it has a reference to, with the -/// and the length of that object, so they'll be valid for the duration of -/// the call. +/// and the length of that object, so they'll be valid for the duration of the +/// call. pub(crate) unsafe fn call_with_sockaddr( addr: &A, f: impl FnOnce(*const SocketAddrOpaque, SocketAddrLen) -> R, diff --git a/src/net/send_recv/msg.rs b/src/net/send_recv/msg.rs index df8c56305..43fe4d907 100644 --- a/src/net/send_recv/msg.rs +++ b/src/net/send_recv/msg.rs @@ -651,9 +651,9 @@ impl<'a> MMsgHdr<'a> { /// `sendmsg(msghdr)`—Sends a message on a socket. /// -/// This function is for use on connected sockets, as it doesn't have -/// a way to specify an address. See [`sendmsg_addr`] to send -/// messages on unconnected sockets. +/// This function is for use on connected sockets, as it doesn't have a way to +/// specify an address. See [`sendmsg_addr`] to send messages on unconnected +/// sockets. /// /// # References /// - [POSIX] @@ -764,9 +764,9 @@ pub fn recvmsg( pub struct RecvMsg { /// The number of bytes received. /// - /// When `RecvFlags::TRUNC` is in use, this may be greater than the - /// length of the buffer, as it reflects the number of bytes received - /// before truncation into the buffer. + /// When `RecvFlags::TRUNC` is in use, this may be greater than the length + /// of the buffer, as it reflects the number of bytes received before + /// truncation into the buffer. pub bytes: usize, /// The flags received. diff --git a/src/net/socket_addr_any.rs b/src/net/socket_addr_any.rs index 0f650e78c..f46462493 100644 --- a/src/net/socket_addr_any.rs +++ b/src/net/socket_addr_any.rs @@ -14,8 +14,8 @@ use core::fmt; use core::mem::{size_of, MaybeUninit}; use core::num::NonZeroU32; -/// Temporary buffer for creating a `SocketAddrAny` from a -/// syscall that writes to a `sockaddr_t` and `socklen_t` +/// Temporary buffer for creating a `SocketAddrAny` from a syscall that writes +/// to a `sockaddr_t` and `socklen_t` /// /// Unlike `SocketAddrAny`, this does not maintain the invariant that `len` /// bytes are initialized. @@ -37,8 +37,8 @@ impl SocketAddrBuf { /// /// # Safety /// - /// A valid address must have been written into `self.storage` - /// and its length written into `self.len`. + /// A valid address must have been written into `self.storage` and its + /// length written into `self.len`. #[inline] pub(crate) unsafe fn into_any(self) -> SocketAddrAny { SocketAddrAny::new(self.storage, bitcast!(self.len)) @@ -51,9 +51,8 @@ impl SocketAddrBuf { /// /// # Safety /// - /// Either valid address must have been written into `self.storage` - /// and its length written into `self.len`, or `self.len` must - /// have been set to 0. + /// Either valid address must have been written into `self.storage` and its + /// length written into `self.len`, or `self.len` must have been set to 0. #[inline] pub(crate) unsafe fn into_any_option(self) -> Option { let len = bitcast!(self.len); @@ -85,8 +84,8 @@ pub struct SocketAddrAny { } impl SocketAddrAny { - /// Creates a socket address from `storage`, which is initialized for - /// `len` bytes. + /// Creates a socket address from `storage`, which is initialized for `len` + /// bytes. /// /// # Panics /// diff --git a/src/net/types.rs b/src/net/types.rs index 1efc3e73a..8a7a0813f 100644 --- a/src/net/types.rs +++ b/src/net/types.rs @@ -1639,7 +1639,7 @@ pub mod xdp { // Constant needs to be cast because bindgen does generate a u32 but the struct // expects a u16. - // + // bitflags! { /// `XDP_*` constants for use in [`SocketAddrXdp`]. #[repr(transparent)] @@ -1684,7 +1684,7 @@ pub mod xdp { /// Used to bind to XDP socket. /// /// Not ABI compatible with `struct sockaddr_xdp` - // + // #[derive(Clone, PartialEq, PartialOrd, Eq, Ord, Hash, Debug)] pub struct SocketAddrXdp { /// Flags. @@ -1803,7 +1803,7 @@ pub mod xdp { /// Used to mmap rings from kernel. /// /// Not ABI compatible with `struct xdp_ring_offset`. - // + // #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct XdpRingOffset { /// Producer offset. @@ -1821,7 +1821,7 @@ pub mod xdp { /// XDP mmap offsets. /// /// Not ABI compatible with `struct xdp_mmap_offsets` - // + // #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct XdpMmapOffsets { /// Rx ring offsets. @@ -1837,7 +1837,7 @@ pub mod xdp { /// XDP umem registration. /// /// `struct xdp_umem_reg` - // + // #[repr(C)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct XdpUmemReg { @@ -1862,7 +1862,7 @@ pub mod xdp { /// XDP statistics. /// /// Not ABI compatible with `struct xdp_statistics` - // + // #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct XdpStatistics { /// Rx dropped. @@ -1889,7 +1889,7 @@ pub mod xdp { /// /// Requires kernel version 5.3. /// `struct xdp_options` - // + // #[repr(C)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct XdpOptions { @@ -1900,7 +1900,7 @@ pub mod xdp { /// XDP rx/tx frame descriptor. /// /// `struct xdp_desc` - // + // #[repr(C)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct XdpDesc { diff --git a/src/not_implemented.rs b/src/not_implemented.rs index a851825b1..67b8a3f82 100644 --- a/src/not_implemented.rs +++ b/src/not_implemented.rs @@ -1,4 +1,4 @@ -//! Unimplemented functions. +//! 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 @@ -21,7 +21,7 @@ macro_rules! not_implemented { /// /// There are several allocator implementations for Rust; one of them is /// [dlmalloc]. For a rustix-based implementation, see [rustix-dlmalloc]. -/// Another allocator implementaion is [talc]. +/// Another allocator implementation is [talc]. /// /// [dlmalloc]: https://crates.io/crates/dlmalloc /// [talc]: https://crates.io/crates/talc @@ -289,11 +289,11 @@ pub mod yet { not_implemented!(shmctl); } -/// These functions are not yet finished in rustix. +/// These functions are not quite yet finished in rustix. /// /// Rustix's codebase includes experimental implementations of these functions, /// however they are not yet publicly exposed because their API might need more -/// work and/or they don't yet have a libc backend implementation. +/// work and/or they don't yet have a libc backend implementation yet. /// /// See [#1314] for more information, and please leave comments if there are /// specific functions you're interested in. diff --git a/src/pipe.rs b/src/pipe.rs index 2f9911892..1de3ecb37 100644 --- a/src/pipe.rs +++ b/src/pipe.rs @@ -1,8 +1,4 @@ //! `pipe` and related APIs. -//! -//! # Safety -//! -//! `vmsplice` is an unsafe function. #![allow(unsafe_code)] diff --git a/src/prctl.rs b/src/prctl.rs index 004493333..1a31a8cc4 100644 --- a/src/prctl.rs +++ b/src/prctl.rs @@ -11,7 +11,7 @@ use core::mem::MaybeUninit; use core::ptr::null_mut; bitflags! { - /// `PR_PAC_AP*`. + /// `PR_PAC_AP*` #[repr(transparent)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct PointerAuthenticationKeys: u32 { diff --git a/src/process/pidfd.rs b/src/process/pidfd.rs index 0755055d2..f812a9f61 100644 --- a/src/process/pidfd.rs +++ b/src/process/pidfd.rs @@ -10,7 +10,7 @@ bitflags::bitflags! { #[repr(transparent)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct PidfdFlags: ffi::c_uint { - /// `PIDFD_NONBLOCK`. + /// `PIDFD_NONBLOCK` const NONBLOCK = backend::c::PIDFD_NONBLOCK; /// diff --git a/src/process/prctl.rs b/src/process/prctl.rs index 3b5b1a0a0..bfd2d46ba 100644 --- a/src/process/prctl.rs +++ b/src/process/prctl.rs @@ -1007,7 +1007,7 @@ bitflags! { /// # References /// - [`prctl(PR_GET_SPECULATION_CTRL,…)`] /// -/// [`prctl(PR_GET_SPECULATION_CTRL,…)`]: https://www.kernel.org/doc/html/v6.10/userspace-api/spec_ctrl.html +/// [`prctl(PR_GET_SPECULATION_CTRL,…)`]: https://www.kernel.org/doc/html/v6.13/userspace-api/spec_ctrl.html #[inline] #[doc(alias = "PR_GET_SPECULATION_CTRL")] pub fn speculative_feature_state( @@ -1024,7 +1024,7 @@ const PR_SET_SPECULATION_CTRL: c_int = 53; /// # References /// - [`prctl(PR_SET_SPECULATION_CTRL,…)`] /// -/// [`prctl(PR_SET_SPECULATION_CTRL,…)`]: https://www.kernel.org/doc/html/v6.10/userspace-api/spec_ctrl.html +/// [`prctl(PR_SET_SPECULATION_CTRL,…)`]: https://www.kernel.org/doc/html/v6.13/userspace-api/spec_ctrl.html #[inline] #[doc(alias = "PR_SET_SPECULATION_CTRL")] pub fn control_speculative_feature( @@ -1080,7 +1080,7 @@ const PR_PAC_GET_ENABLED_KEYS: c_int = 61; /// # References /// - [`prctl(PR_PAC_GET_ENABLED_KEYS,…)`] /// -/// [`prctl(PR_PAC_GET_ENABLED_KEYS,…)`]: https://www.kernel.org/doc/html/v6.10/arch/arm64/pointer-authentication.html +/// [`prctl(PR_PAC_GET_ENABLED_KEYS,…)`]: https://www.kernel.org/doc/html/v6.13/arch/arm64/pointer-authentication.html #[inline] #[doc(alias = "PR_PAC_GET_ENABLED_KEYS")] pub fn enabled_pointer_authentication_keys() -> io::Result { @@ -1100,7 +1100,7 @@ const PR_PAC_SET_ENABLED_KEYS: c_int = 60; /// Please ensure the conditions necessary to safely call this function, as /// detailed in the references above. /// -/// [`prctl(PR_PAC_SET_ENABLED_KEYS,…)`]: https://www.kernel.org/doc/html/v6.10/arch/arm64/pointer-authentication.html +/// [`prctl(PR_PAC_SET_ENABLED_KEYS,…)`]: https://www.kernel.org/doc/html/v6.13/arch/arm64/pointer-authentication.html #[inline] #[doc(alias = "PR_PAC_SET_ENABLED_KEYS")] pub unsafe fn configure_pointer_authentication_keys< diff --git a/src/process/procctl.rs b/src/process/procctl.rs index 8c38ef241..8eaa9858f 100644 --- a/src/process/procctl.rs +++ b/src/process/procctl.rs @@ -133,7 +133,7 @@ const PROC_TRACE_CTL_ENABLE: i32 = 1; const PROC_TRACE_CTL_DISABLE: i32 = 2; const PROC_TRACE_CTL_DISABLE_EXEC: i32 = 3; -/// `PROC_TRACE_CTL_*`. +/// `PROC_TRACE_CTL_*` #[derive(Copy, Clone, Debug, Eq, PartialEq)] #[repr(i32)] pub enum DumpableBehavior { @@ -235,7 +235,7 @@ pub fn set_reaper_status(reaper: bool) -> io::Result<()> { const PROC_REAP_STATUS: c_int = 4; bitflags! { - /// `REAPER_STATUS_*`. + /// `REAPER_STATUS_*` #[repr(transparent)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct ReaperStatusFlags: c_uint { @@ -302,7 +302,7 @@ pub fn get_reaper_status(process: ProcSelector) -> io::Result { const PROC_REAP_GETPIDS: c_int = 5; bitflags! { - /// `REAPER_PIDINFO_*`. + /// `REAPER_PIDINFO_*` #[repr(transparent)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct PidInfoFlags: c_uint { @@ -387,7 +387,7 @@ pub fn get_reaper_pids(process: ProcSelector) -> io::Result> { const PROC_REAP_KILL: c_int = 6; bitflags! { - /// `REAPER_KILL_*`. + /// `REAPER_KILL_*` #[repr(transparent)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] struct KillFlags: c_uint { @@ -454,7 +454,7 @@ const PROC_TRAPCAP_CTL: c_int = 9; const PROC_TRAPCAP_CTL_ENABLE: i32 = 1; const PROC_TRAPCAP_CTL_DISABLE: i32 = 2; -/// `PROC_TRAPCAP_CTL_*`. +/// `PROC_TRAPCAP_CTL_*` #[derive(Copy, Clone, Debug, Eq, PartialEq)] #[repr(i32)] pub enum TrapCapBehavior { diff --git a/src/runtime.rs b/src/runtime.rs index 2ef2000c9..937644e76 100644 --- a/src/runtime.rs +++ b/src/runtime.rs @@ -83,7 +83,7 @@ pub use linux_raw_sys::general::stack_t as Stack; #[cfg(linux_raw)] pub use linux_raw_sys::general::sigset_t as SigSet; -/// `kernel_sigset_t`. +/// `kernel_sigset_t` /// /// Undefined behavior could happen in some functions if `KernelSigSet` ever /// contains signal numbers in the range from `KERNEL_SIGRTMIN` to the libc diff --git a/src/signal.rs b/src/signal.rs index fffd0fcaa..3c381c0ae 100644 --- a/src/signal.rs +++ b/src/signal.rs @@ -3,9 +3,12 @@ //! # Safety //! //! Some signal numbers are reserved by the libc. -//! [`Signal::from_raw_unchecked`] allows constructing `Signal` values with -//! arbitrary values. Users must avoid using these values to send or -//! consume signals in any way. +//! [`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. #![allow(unsafe_code)] use crate::backend::c; @@ -39,8 +42,8 @@ impl Signal { /// `SIGTRAP` pub const TRAP: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGTRAP) }); /// `SIGABRT`, aka `SIGIOT` - #[doc(alias = "Iot")] - #[doc(alias = "Abrt")] + #[doc(alias = "IOT")] + #[doc(alias = "ABRT")] pub const ABORT: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGABRT) }); /// `SIGBUS` pub const BUS: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGBUS) }); @@ -59,7 +62,7 @@ impl Signal { /// `SIGPIPE` pub const PIPE: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGPIPE) }); /// `SIGALRM` - #[doc(alias = "Alrm")] + #[doc(alias = "ALRM")] pub const ALARM: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGALRM) }); /// `SIGTERM` pub const TERM: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGTERM) }); @@ -87,7 +90,7 @@ impl Signal { pub const STKFLT: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGSTKFLT) }); /// `SIGCHLD` #[cfg(not(target_os = "vita"))] - #[doc(alias = "Chld")] + #[doc(alias = "CHLD")] pub const CHILD: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGCHLD) }); /// `SIGCONT` #[cfg(not(target_os = "vita"))] @@ -115,7 +118,7 @@ impl Signal { pub const XFSZ: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGXFSZ) }); /// `SIGVTALRM` #[cfg(not(target_os = "vita"))] - #[doc(alias = "Vtalrm")] + #[doc(alias = "VTALRM")] pub const VTALARM: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGVTALRM) }); /// `SIGPROF` #[cfg(not(target_os = "vita"))] @@ -124,15 +127,15 @@ impl Signal { #[cfg(not(target_os = "vita"))] pub const WINCH: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGWINCH) }); /// `SIGIO`, aka `SIGPOLL` - #[doc(alias = "Poll")] + #[doc(alias = "POLL")] #[cfg(not(any(target_os = "haiku", target_os = "vita")))] pub const IO: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGIO) }); /// `SIGPWR` #[cfg(not(any(bsd, target_os = "haiku", target_os = "hurd", target_os = "vita")))] - #[doc(alias = "Pwr")] + #[doc(alias = "PWR")] pub const POWER: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGPWR) }); /// `SIGSYS`, aka `SIGUNUSED` - #[doc(alias = "Unused")] + #[doc(alias = "UNUSED")] pub const SYS: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGSYS) }); /// `SIGEMT` #[cfg(any( @@ -158,7 +161,7 @@ impl Signal { pub const INFO: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGINFO) }); /// `SIGTHR` #[cfg(target_os = "freebsd")] - #[doc(alias = "Lwp")] + #[doc(alias = "LWP")] pub const THR: Self = Self(unsafe { NonZeroI32::new_unchecked(c::SIGTHR) }); /// `SIGLIBRT` #[cfg(target_os = "freebsd")] @@ -182,9 +185,10 @@ impl Signal { /// `SIGRTMIN + n`—Convert a “real-time” signal offset into a `Signal`. /// - /// This function adds `n` to the libc `SIGRTMIN` value to construct the - /// raw signal value. If the result is greater than the platform `SIGRTMAX` - /// value, it returns `None`. + /// This function adds `n` to `rt_min()` to construct the raw signal value. + /// If the result is greater than `rt_max()`, it returns `None`. This + /// prevents it from returning `Signal` values which would be reserved by + /// the libc for internal use. #[doc(alias = "SIGRTMIN", alias = "SIGRTMAX")] #[cfg(feature = "use-libc-sigrt")] #[cfg_attr(docsrs, doc(cfg(feature = "use-libc-sigrt")))] @@ -203,6 +207,10 @@ impl Signal { /// `SIGRTMIN`—Return the minimum “real-time” signal value. /// + /// This returns the libc `SIGRTMIN` value, which may be different from the + /// OS kernel `SIGRTMIN` value to allow libc to reserve some signals for + /// internal use. + /// /// Use [`Signal::rt`] to construct `SIGRTMIN + n` values. #[doc(alias = "SIGRTMIN")] #[cfg(feature = "use-libc-sigrt")] @@ -214,6 +222,10 @@ impl Signal { } /// `SIGRTMAX`—Return the maximum “real-time” signal value. + /// + /// This returns the libc `SIGRTMAX` value, which may be different from the + /// OS kernel `SIGRTMAX` value to allow libc to reserve some signals for + /// internal use. #[doc(alias = "SIGRTMAX")] #[cfg(feature = "use-libc-sigrt")] #[cfg_attr(docsrs, doc(cfg(feature = "use-libc-sigrt")))] @@ -224,6 +236,9 @@ impl Signal { } /// Convert a raw signal number into a `Signal`. + /// + /// Returns `None` if the signal value is unrecognized, out of range, or + /// reserved for libc. #[cfg(feature = "use-libc-sigrt")] #[cfg_attr(docsrs, doc(cfg(feature = "use-libc-sigrt")))] #[cfg(any(linux_like, solarish, target_os = "hurd"))] @@ -236,6 +251,9 @@ impl Signal { } /// Convert a raw non-zero signal number into a `Signal`. + /// + /// Returns `None` if the signal value is unrecognized, out of range, or + /// reserved for libc. #[cfg(feature = "use-libc-sigrt")] #[cfg_attr(docsrs, doc(cfg(feature = "use-libc-sigrt")))] #[cfg(any(linux_like, solarish, target_os = "hurd"))] @@ -358,8 +376,8 @@ impl Signal { /// from [`SIGRTMIN`] to [`SIGRTMAX`] inclusive, then the resulting /// `Signal` must not be used to send any signals. /// - /// [`SIGRTMIN`]: https://docs.rs/libc/latest/libc/fn.SIGRTMIN.html - /// [`SIGRTMAX`]: https://docs.rs/libc/latest/libc/fn.SIGRTMAX.html + /// [`SIGRTMIN`]: https://docs.rs/libc/*/libc/fn.SIGRTMIN.html + /// [`SIGRTMAX`]: https://docs.rs/libc/*/libc/fn.SIGRTMAX.html #[inline] pub const unsafe fn from_raw_unchecked(sig: i32) -> Self { Self::from_raw_nonzero_unchecked(NonZeroI32::new_unchecked(sig)) @@ -377,8 +395,8 @@ impl Signal { /// from [`SIGRTMIN`] to [`SIGRTMAX`] inclusive, then the resulting /// `Signal` must not be used to send any signals. /// - /// [`SIGRTMIN`]: https://docs.rs/libc/latest/libc/fn.SIGRTMIN.html - /// [`SIGRTMAX`]: https://docs.rs/libc/latest/libc/fn.SIGRTMAX.html + /// [`SIGRTMIN`]: https://docs.rs/libc/*/libc/fn.SIGRTMIN.html + /// [`SIGRTMAX`]: https://docs.rs/libc/*/libc/fn.SIGRTMAX.html #[inline] pub const unsafe fn from_raw_nonzero_unchecked(sig: NonZeroI32) -> Self { Self(sig) diff --git a/src/stdio.rs b/src/stdio.rs index 759ef1009..23d44ac1a 100644 --- a/src/stdio.rs +++ b/src/stdio.rs @@ -2,10 +2,15 @@ //! //! # 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. +//! 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. #![allow(unsafe_code)] use crate::backend; @@ -67,10 +72,10 @@ pub const fn stdin() -> BorrowedFd<'static> { /// /// # Safety /// -/// In `no_std` configurations, the stdin file descriptor can be closed, -/// potentially on other threads, in which case the file descriptor index -/// value could be dynamically reused for other purposes, potentially on -/// different threads. +/// In `no_std` configurations, the process' stdin file descriptor can be +/// closed, potentially on other threads, in which case the file descriptor +/// index number (`STDIN_FILENO`) could be dynamically reused for other +/// purposes, potentially on different threads. /// /// # Warning /// @@ -189,10 +194,10 @@ pub const fn stdout() -> BorrowedFd<'static> { /// /// # Safety /// -/// In `no_std` configurations, the stdout file descriptor can be closed, -/// potentially on other threads, in which case the file descriptor index -/// value could be dynamically reused for other purposes, potentially on -/// different threads. +/// In `no_std` configurations, the process' stdout file descriptor can be +/// closed, potentially on other threads, in which case the file descriptor +/// index number (`STDOUT_FILENO`) could be dynamically reused for other +/// purposes, potentially on different threads. /// /// # Warning /// @@ -305,10 +310,10 @@ pub const fn stderr() -> BorrowedFd<'static> { /// /// # Safety /// -/// In `no_std` configurations, the stderr file descriptor can be closed, -/// potentially on other threads, in which case the file descriptor index -/// value could be dynamically reused for other purposes, potentially on -/// different threads. +/// In `no_std` configurations, the process' stderr file descriptor can be +/// closed, potentially on other threads, in which case the file descriptor +/// index number (`STDERR_FILENO`) could be dynamically reused for other +/// purposes, potentially on different threads. /// /// # References /// - [POSIX] diff --git a/src/system.rs b/src/system.rs index 97568790a..a46c1c77b 100644 --- a/src/system.rs +++ b/src/system.rs @@ -1,9 +1,5 @@ //! 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. + #![allow(unsafe_code)] use crate::backend; diff --git a/src/termios/ioctl.rs b/src/termios/ioctl.rs index 5999949a0..85098a770 100644 --- a/src/termios/ioctl.rs +++ b/src/termios/ioctl.rs @@ -8,7 +8,7 @@ use backend::c; /// `ioctl(fd, TIOCEXCL)`—Enables exclusive mode on a terminal. /// -/// In exclusive mode, subsequent unpriveleged `open` calls on the terminal +/// In exclusive mode, subsequent unprivileged `open` calls on the terminal /// device fail with [`io::Errno::BUSY`]. /// /// # References diff --git a/src/thread/prctl.rs b/src/thread/prctl.rs index 370778690..51e91890e 100644 --- a/src/thread/prctl.rs +++ b/src/thread/prctl.rs @@ -106,7 +106,7 @@ const SECCOMP_MODE_DISABLED: i32 = 0; const SECCOMP_MODE_STRICT: i32 = 1; const SECCOMP_MODE_FILTER: i32 = 2; -/// `SECCOMP_MODE_*`. +/// `SECCOMP_MODE_*` #[derive(Copy, Clone, Debug, Eq, PartialEq)] #[repr(i32)] pub enum SecureComputingMode { @@ -416,7 +416,7 @@ pub fn remove_capability_from_bounding_set(capability: Capability) -> io::Result const PR_GET_SECUREBITS: c_int = 27; bitflags! { - /// `SECBIT_*`. + /// `SECBIT_*` #[repr(transparent)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct CapabilitiesSecureBits: u32 { @@ -899,7 +899,7 @@ const PR_SCHED_CORE_SCOPE_THREAD: u32 = 0; const PR_SCHED_CORE_SCOPE_THREAD_GROUP: u32 = 1; const PR_SCHED_CORE_SCOPE_PROCESS_GROUP: u32 = 2; -/// `PR_SCHED_CORE_SCOPE_*`. +/// `PR_SCHED_CORE_SCOPE_*` #[derive(Copy, Clone, Debug, Eq, PartialEq)] #[repr(u32)] pub enum CoreSchedulingScope { @@ -930,7 +930,7 @@ impl TryFrom for CoreSchedulingScope { /// # References /// - [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_GET,…)`] /// -/// [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_GET,…)`]: https://www.kernel.org/doc/html/v6.10/admin-guide/hw-vuln/core-scheduling.html +/// [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_GET,…)`]: https://www.kernel.org/doc/html/v6.13/admin-guide/hw-vuln/core-scheduling.html #[inline] pub fn core_scheduling_cookie(pid: Pid, scope: CoreSchedulingScope) -> io::Result { let mut value: MaybeUninit = MaybeUninit::uninit(); @@ -953,7 +953,7 @@ const PR_SCHED_CORE_CREATE: usize = 1; /// # References /// - [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_CREATE,…)`] /// -/// [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_CREATE,…)`]: https://www.kernel.org/doc/html/v6.10/admin-guide/hw-vuln/core-scheduling.html +/// [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_CREATE,…)`]: https://www.kernel.org/doc/html/v6.13/admin-guide/hw-vuln/core-scheduling.html #[inline] pub fn create_core_scheduling_cookie(pid: Pid, scope: CoreSchedulingScope) -> io::Result<()> { unsafe { @@ -975,7 +975,7 @@ const PR_SCHED_CORE_SHARE_TO: usize = 2; /// # References /// - [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_SHARE_TO,…)`] /// -/// [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_SHARE_TO,…)`]: https://www.kernel.org/doc/html/v6.10/admin-guide/hw-vuln/core-scheduling.html +/// [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_SHARE_TO,…)`]: https://www.kernel.org/doc/html/v6.13/admin-guide/hw-vuln/core-scheduling.html #[inline] pub fn push_core_scheduling_cookie(pid: Pid, scope: CoreSchedulingScope) -> io::Result<()> { unsafe { @@ -997,7 +997,7 @@ const PR_SCHED_CORE_SHARE_FROM: usize = 3; /// # References /// - [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_SHARE_FROM,…)`] /// -/// [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_SHARE_FROM,…)`]: https://www.kernel.org/doc/html/v6.10/admin-guide/hw-vuln/core-scheduling.html +/// [`prctl(PR_SCHED_CORE,PR_SCHED_CORE_SHARE_FROM,…)`]: https://www.kernel.org/doc/html/v6.13/admin-guide/hw-vuln/core-scheduling.html #[inline] pub fn pull_core_scheduling_cookie(pid: Pid, scope: CoreSchedulingScope) -> io::Result<()> { unsafe { diff --git a/src/thread/setns.rs b/src/thread/setns.rs index 48279dcda..0eaee2f2a 100644 --- a/src/thread/setns.rs +++ b/src/thread/setns.rs @@ -63,27 +63,27 @@ bitflags! { #[repr(transparent)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct UnshareFlags: u32 { - /// `CLONE_FILES`. + /// `CLONE_FILES` const FILES = CLONE_FILES; - /// `CLONE_FS`. + /// `CLONE_FS` const FS = CLONE_FS; - /// `CLONE_NEWCGROUP`. + /// `CLONE_NEWCGROUP` const NEWCGROUP = CLONE_NEWCGROUP; - /// `CLONE_NEWIPC`. + /// `CLONE_NEWIPC` const NEWIPC = CLONE_NEWIPC; - /// `CLONE_NEWNET`. + /// `CLONE_NEWNET` const NEWNET = CLONE_NEWNET; - /// `CLONE_NEWNS`. + /// `CLONE_NEWNS` const NEWNS = CLONE_NEWNS; - /// `CLONE_NEWPID`. + /// `CLONE_NEWPID` const NEWPID = CLONE_NEWPID; - /// `CLONE_NEWTIME`. + /// `CLONE_NEWTIME` const NEWTIME = CLONE_NEWTIME; - /// `CLONE_NEWUSER`. + /// `CLONE_NEWUSER` const NEWUSER = CLONE_NEWUSER; /// `CLONE_NEWUTS` const NEWUTS = CLONE_NEWUTS; - /// `CLONE_SYSVSEM`. + /// `CLONE_SYSVSEM` const SYSVSEM = CLONE_SYSVSEM; /// diff --git a/tests/net/sockopt.rs b/tests/net/sockopt.rs index 0f4757955..e786f4239 100644 --- a/tests/net/sockopt.rs +++ b/tests/net/sockopt.rs @@ -429,17 +429,17 @@ fn test_sockopts_ipv6() { Err(err) => panic!("{:?}", err), }; - // Set the IPV4 V6OONLY value. + // Set the IPv4 V6OONLY value. let v6only = rustix::net::sockopt::ipv6_v6only(&s).unwrap(); sockopt::set_ipv6_v6only(&s, !v6only).unwrap(); - // Check that the IPV6 V6ONLY value is set. + // Check that the IPv6 V6ONLY value is set. assert_eq!(sockopt::ipv6_v6only(&s).unwrap(), !v6only); - // Set the IPV6 multicast loop value. + // Set the IPv6 multicast loop value. match sockopt::set_ipv6_multicast_loop(&s, false) { Ok(()) => { - // Check that the IPV6 multicast loop value is set. + // Check that the IPv6 multicast loop value is set. match sockopt::ipv6_multicast_loop(&s) { Ok(multicast_loop) => assert!(!multicast_loop), Err(err) => panic!("{:?}", err), @@ -451,16 +451,16 @@ fn test_sockopts_ipv6() { Err(err) => panic!("{:?}", err), } - // Set the IPV6 unicast hops value to the default value. + // Set the IPv6 unicast hops value to the default value. sockopt::set_ipv6_unicast_hops(&s, None).unwrap(); - // Check that the IPV6 unicast hops value is set. + // Check that the IPv6 unicast hops value is set. assert_ne!(sockopt::ipv6_unicast_hops(&s).unwrap(), 0); - // Set the IPV6 unicast hops value to a specific value. + // Set the IPv6 unicast hops value to a specific value. sockopt::set_ipv6_unicast_hops(&s, Some(8)).unwrap(); - // Check that the IPV6 unicast hops value is set. + // Check that the IPv6 unicast hops value is set. assert_eq!(sockopt::ipv6_unicast_hops(&s).unwrap(), 8); // Check the initial value of `IPV6_RECVTCLASS`, set it, and check it. @@ -560,7 +560,7 @@ fn test_sockopts_multicast_ifv4() { let s = rustix::net::socket(AddressFamily::INET, SocketType::DGRAM, None).unwrap(); - // Set a ipv4 interface + // Set a IPv4 interface match sockopt::set_ip_multicast_if(&s, &Ipv4Addr::LOCALHOST) { Ok(_) => { assert_eq!(sockopt::ip_multicast_if(&s).unwrap(), Ipv4Addr::LOCALHOST); @@ -588,7 +588,7 @@ fn test_sockopts_multicast_if_with_ifindex() { .unwrap(); let index = rustix::net::netdevice::name_to_index(&fd, "lo").unwrap(); - // Set a ipv4 interface + // Set a IPv4 interface match sockopt::set_ip_multicast_if_with_ifindex( &s, &Ipv4Addr::new(224, 254, 0, 0), @@ -611,7 +611,7 @@ fn test_sockopts_multicast_ifv6() { let s = rustix::net::socket(AddressFamily::INET6, SocketType::DGRAM, None).unwrap(); - // Set a ipv6 interface + // Set a IPv6 interface match sockopt::set_ipv6_multicast_if(&s, 1) { Ok(_) => { assert_eq!(sockopt::ipv6_multicast_if(&s).unwrap(), 1);