Skip to content

Commit

Permalink
Miscellaneous documentation cleanups. (#887)
Browse files Browse the repository at this point in the history
  • Loading branch information
sunfishcode authored Oct 19, 2023
1 parent a59a191 commit ce11b6c
Show file tree
Hide file tree
Showing 27 changed files with 95 additions and 98 deletions.
15 changes: 7 additions & 8 deletions src/backend/libc/fs/inotify.rs
Original file line number Diff line number Diff line change
Expand Up @@ -90,15 +90,14 @@ pub fn inotify_init(flags: CreateFlags) -> io::Result<OwnedFd> {
unsafe { ret_owned_fd(c::inotify_init1(bitflags_bits!(flags))) }
}

/// `inotify_add_watch(self, path, flags)`—Adds a watch to inotify
/// `inotify_add_watch(self, path, flags)`—Adds a watch to inotify.
///
/// This registers or updates a watch for the filesystem path `path`
/// and returns a watch descriptor corresponding to this watch.
/// This registers or updates a watch for the filesystem path `path` and
/// returns a watch descriptor corresponding to this watch.
///
/// Note: Due to the existence of hardlinks, providing two
/// different paths to this method may result in it returning
/// the same watch descriptor. An application should keep track of this
/// externally to avoid logic errors.
/// Note: Due to the existence of hardlinks, providing two different paths to
/// this method may result in it returning the same watch descriptor. An
/// application should keep track of this externally to avoid logic errors.
pub fn inotify_add_watch<P: crate::path::Arg>(
inot: BorrowedFd<'_>,
path: P,
Expand All @@ -117,7 +116,7 @@ pub fn inotify_add_watch<P: crate::path::Arg>(
})
}

/// `inotify_rm_watch(self, wd)`—Removes a watch from this inotify
/// `inotify_rm_watch(self, wd)`—Removes a watch from this inotify.
///
/// The watch descriptor provided should have previously been returned by
/// [`inotify_add_watch`] and not previously have been removed.
Expand Down
2 changes: 1 addition & 1 deletion src/backend/libc/mm/syscalls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ pub(crate) unsafe fn userfaultfd(flags: UserfaultfdFlags) -> io::Result<OwnedFd>

/// Locks all pages mapped into the address space of the calling process.
///
/// This includes the pages of the code, data and stack segment, as well as
/// This includes the pages of the code, data, and stack segment, as well as
/// shared libraries, user space kernel data, shared memory, and memory-mapped
/// files. All mapped pages are guaranteed to be resident in RAM when the call
/// returns successfully; the pages are guaranteed to stay in RAM until later
Expand Down
13 changes: 6 additions & 7 deletions src/backend/libc/mm/types.rs
Original file line number Diff line number Diff line change
Expand Up @@ -453,14 +453,13 @@ bitflags! {
pub struct MlockAllFlags: u32 {
// libc doesn't define `MCL_ONFAULT` yet.
// const ONFAULT = libc::MCL_ONFAULT;
/// Lock all pages which will become mapped into the address
/// space of the process in the future. These could be, for
/// instance, new pages required by a growing heap and stack
/// as well as new memory-mapped files or shared memory
/// regions.
/// Lock all pages which will become mapped into the address space of
/// the process in the future. These could be, for instance, new pages
/// required by a growing heap and stack as well as new memory-mapped
/// files or shared memory regions.
const FUTURE = bitcast!(libc::MCL_FUTURE);
/// Lock all pages which are currently mapped into the address
/// space of the process.
/// Lock all pages which are currently mapped into the address space of
/// the process.
const CURRENT = bitcast!(libc::MCL_CURRENT);

/// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
Expand Down
11 changes: 5 additions & 6 deletions src/backend/linux_raw/fs/inotify.rs
Original file line number Diff line number Diff line change
Expand Up @@ -92,13 +92,12 @@ pub fn inotify_init(flags: CreateFlags) -> io::Result<OwnedFd> {

/// `inotify_add_watch(self, path, flags)`—Adds a watch to inotify.
///
/// This registers or updates a watch for the filesystem path `path`
/// and returns a watch descriptor corresponding to this watch.
/// This registers or updates a watch for the filesystem path `path` and
/// returns a watch descriptor corresponding to this watch.
///
/// Note: Due to the existence of hardlinks, providing two
/// different paths to this method may result in it returning
/// the same watch descriptor. An application should keep track of this
/// externally to avoid logic errors.
/// Note: Due to the existence of hardlinks, providing two different paths to
/// this method may result in it returning the same watch descriptor. An
/// application should keep track of this externally to avoid logic errors.
#[inline]
pub fn inotify_add_watch<P: crate::path::Arg>(
inot: BorrowedFd<'_>,
Expand Down
2 changes: 1 addition & 1 deletion src/backend/linux_raw/io/errno.rs
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ impl Errno {
#[inline]
pub fn from_io_error(io_err: &std::io::Error) -> Option<Self> {
io_err.raw_os_error().and_then(|raw| {
// `std::io::Error` could theoretically have arbitrary "OS error"
// `std::io::Error` could theoretically have arbitrary OS error
// values, so check that they're in Linux's range.
if (1..4096).contains(&raw) {
Some(Self::from_errno(raw as u32))
Expand Down
2 changes: 1 addition & 1 deletion src/backend/linux_raw/mm/syscalls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ pub(crate) unsafe fn userfaultfd(flags: UserfaultfdFlags) -> io::Result<OwnedFd>

/// Locks all pages mapped into the address space of the calling process.
///
/// This includes the pages of the code, data and stack segment, as well as
/// This includes the pages of the code, data, and stack segment, as well as
/// shared libraries, user space kernel data, shared memory, and memory-mapped
/// files. All mapped pages are guaranteed to be resident in RAM when the call
/// returns successfully; the pages are guaranteed to stay in RAM until later
Expand Down
36 changes: 17 additions & 19 deletions src/backend/linux_raw/mm/types.rs
Original file line number Diff line number Diff line change
Expand Up @@ -240,9 +240,9 @@ pub enum Advice {
impl Advice {
/// `POSIX_MADV_DONTNEED`
///
/// On Linux, this is mapped to `POSIX_MADV_NORMAL` because
/// Linux's `MADV_DONTNEED` differs from `POSIX_MADV_DONTNEED`. See
/// `LinuxDontNeed` for the Linux behavior.
/// On Linux, this is mapped to `POSIX_MADV_NORMAL` because Linux's
/// `MADV_DONTNEED` differs from `POSIX_MADV_DONTNEED`. See `LinuxDontNeed`
/// for the Linux behavior.
pub const DontNeed: Self = Self::Normal;
}

Expand Down Expand Up @@ -271,25 +271,23 @@ bitflags! {
#[repr(transparent)]
#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
pub struct MlockAllFlags: u32 {
/// Used together with `MCL_CURRENT`, `MCL_FUTURE`, or both. Mark
/// all current (with `MCL_CURRENT`) or future (with `MCL_FUTURE`)
/// mappings to lock pages when they are faulted in. When
/// used with `MCL_CURRENT`, all present pages are locked, but
/// `mlockall()` will not fault in non-present pages. When used
/// with `MCL_FUTURE`, all future mappings will be marked to
/// lock pages when they are faulted in, but they will not be
/// populated by the lock when the mapping is created.
/// `MCL_ONFAULT` must be used with either `MCL_CURRENT` or
/// Used together with `MCL_CURRENT`, `MCL_FUTURE`, or both. Mark all
/// current (with `MCL_CURRENT`) or future (with `MCL_FUTURE`) mappings
/// to lock pages when they are faulted in. When used with
/// `MCL_CURRENT`, all present pages are locked, but `mlockall` will
/// not fault in non-present pages. When used with `MCL_FUTURE`, all
/// future mappings will be marked to lock pages when they are faulted
/// in, but they will not be populated by the lock when the mapping is
/// created. `MCL_ONFAULT` must be used with either `MCL_CURRENT` or
/// `MCL_FUTURE` or both.
const ONFAULT = linux_raw_sys::general::MCL_ONFAULT;
/// Lock all pages which will become mapped into the address
/// space of the process in the future. These could be, for
/// instance, new pages required by a growing heap and stack
/// as well as new memory-mapped files or shared memory
/// regions.
/// Lock all pages which will become mapped into the address space of
/// the process in the future. These could be, for instance, new pages
/// required by a growing heap and stack as well as new memory-mapped
/// files or shared memory regions.
const FUTURE = linux_raw_sys::general::MCL_FUTURE;
/// Lock all pages which are currently mapped into the address
/// space of the process.
/// Lock all pages which are currently mapped into the address space of
/// the process.
const CURRENT = linux_raw_sys::general::MCL_CURRENT;

/// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
Expand Down
2 changes: 1 addition & 1 deletion src/backend/linux_raw/param/auxv.rs
Original file line number Diff line number Diff line change
Expand Up @@ -337,7 +337,7 @@ unsafe fn init_from_aux_iter(aux_iter: impl Iterator<Item = Elf_auxv_t>) -> Opti
#[cfg(feature = "runtime")]
assert_eq!(phent, size_of::<Elf_Phdr>());

// If we're running set-uid or set-gid, enable "secure execution" mode,
// If we're running set-uid or set-gid, enable secure execution mode,
// which doesn't do much, but users may be depending on the things that
// it does do.
#[cfg(feature = "runtime")]
Expand Down
2 changes: 1 addition & 1 deletion src/backend/linux_raw/process/syscalls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ pub(crate) fn getpgrp() -> Pid {
#[inline]
pub(crate) fn sched_getaffinity(pid: Option<Pid>, cpuset: &mut RawCpuSet) -> io::Result<()> {
unsafe {
// The raw linux syscall returns the size (in bytes) of the `cpumask_t`
// The raw Linux syscall returns the size (in bytes) of the `cpumask_t`
// data type that is used internally by the kernel to represent the CPU
// set bit mask.
let size = ret_usize(syscall!(
Expand Down
2 changes: 1 addition & 1 deletion src/backend/linux_raw/termios/syscalls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,7 @@ pub(crate) fn ttyname(fd: BorrowedFd<'_>, buf: &mut [MaybeUninit<u8>]) -> io::Re
// Check that `fd` is really a tty.
tcgetwinsize(fd)?;

// Get a fd to '/proc/self/fd'.
// Get a fd to "/proc/self/fd".
let proc_self_fd = procfs::proc_self_fd()?;

// Gather the ttyname by reading the "fd" file inside `proc_self_fd`.
Expand Down
4 changes: 2 additions & 2 deletions src/check_types.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ macro_rules! check_renamed_type {
};
}

/// Check that the field of a struct has the same offset as the
/// corresponding field in the `sys` bindings.
/// Check that the field of a struct has the same offset as the corresponding
/// field in the `sys` bindings.
macro_rules! check_struct_field {
($struct:ident, $field:ident) => {
const_assert_eq!(
Expand Down
8 changes: 4 additions & 4 deletions src/event/kqueue.rs
Original file line number Diff line number Diff line change
Expand Up @@ -73,11 +73,11 @@ impl Event {
flags: flags.bits() as _,
fflags,
data: {
// On openbsd, data is an i64 and not an isize
// On OpenBSD, data is an `i64` and not an `isize`.
data as _
},
udata: {
// On netbsd, udata is an isize and not a pointer.
// On NetBSD, udata is an `isize` and not a pointer.
// TODO: Strict provenance, prevent int-to-ptr cast.
udata as _
},
Expand All @@ -93,15 +93,15 @@ impl Event {

/// Get the user data for this event.
pub fn udata(&self) -> isize {
// On netbsd, udata is an isize and not a pointer.
// On NetBSD, udata is an isize and not a pointer.
// TODO: Strict provenance, prevent ptr-to-int cast.

self.inner.udata as _
}

/// Get the raw data for this event.
pub fn data(&self) -> i64 {
// On some bsds, data is an isize and not an i64
// On some BSDs, data is an `isize` and not an `i64`.
self.inner.data as _
}

Expand Down
23 changes: 11 additions & 12 deletions src/fs/at.rs
Original file line number Diff line number Diff line change
Expand Up @@ -105,22 +105,22 @@ fn _readlinkat(dirfd: BorrowedFd<'_>, path: &CStr, mut buffer: Vec<u8>) -> io::R

debug_assert!(nread <= buffer.capacity());
if nread < buffer.capacity() {
// SAFETY: From the [documentation]: "On success, these calls
// return the number of bytes placed in buf."
// SAFETY: From the [documentation]: On success, these calls
// return the number of bytes placed in buf.
//
// [documentation]: https://man7.org/linux/man-pages/man2/readlinkat.2.html
unsafe {
buffer.set_len(nread);
}

// SAFETY:
// - "readlink places the contents of the symbolic link pathname in the buffer
// buf"
// - [POSIX definition 3.271: Pathname]: "A string that is used to identify a
// file."
// - [POSIX definition 3.375: String]: "A contiguous sequence of bytes
// terminated by and including the first null byte."
// - "readlink does not append a terminating null byte to buf."
// - readlink places the contents of the symbolic link pathname in
// the buffer buf
// - [POSIX definition 3.271: Pathname]: A string that is used to
// identify a file.
// - [POSIX definition 3.375: String]: A contiguous sequence of
// bytes terminated by and including the first null byte.
// - readlink does not append a terminating null byte to buf.
//
// Thus, there will be no NUL bytes in the string.
//
Expand All @@ -131,9 +131,8 @@ fn _readlinkat(dirfd: BorrowedFd<'_>, path: &CStr, mut buffer: Vec<u8>) -> io::R
}
}

buffer.reserve(buffer.capacity() + 1); // use `Vec` reallocation
// strategy to grow capacity
// exponentially
// Use `Vec` reallocation strategy to grow capacity exponentially.
buffer.reserve(buffer.capacity() + 1);
}
}

Expand Down
6 changes: 3 additions & 3 deletions src/ioctl/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ impl Opcode {
Self { raw }
}

/// Create a new opcode from a direction, group, number and size.
/// Create a new opcode from a direction, group, number, and size.
///
/// This corresponds to the C macro `_IOC(direction, group, number, size)`
#[cfg(any(linux_kernel, bsd))]
Expand All @@ -227,8 +227,8 @@ impl Opcode {
))
}

/// Create a new non-mutating opcode from a group, a number and the type of
/// data.
/// Create a new non-mutating opcode from a group, a number, and the type
/// of data.
///
/// This corresponds to the C macro `_IO(group, number)` when `T` is zero
/// sized.
Expand Down
2 changes: 1 addition & 1 deletion src/ioctl/patterns.rs
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ unsafe impl<Opcode: CompileTimeOpcode> Ioctl for NoArg<Opcode> {
}
}

/// Implements the traditional "getter" pattern for `ioctl`s.
/// Implements the traditional getter pattern for `ioctl`s.
///
/// Some `ioctl`s just read data into the userspace. As this is a popular
/// pattern this structure implements it.
Expand Down
4 changes: 2 additions & 2 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -115,9 +115,9 @@
)]
#![cfg_attr(asm_experimental_arch, feature(asm_experimental_arch))]
#![cfg_attr(not(feature = "all-apis"), allow(dead_code))]
// It is common in linux and libc APIs for types to vary between platforms.
// It is common in Linux and libc APIs for types to vary between platforms.
#![allow(clippy::unnecessary_cast)]
// It is common in linux and libc APIs for types to vary between platforms.
// It is common in Linux and libc APIs for types to vary between platforms.
#![allow(clippy::useless_conversion)]
// Redox and WASI have enough differences that it isn't worth precisely
// conditionalizing all the `use`s for them.
Expand Down
2 changes: 1 addition & 1 deletion src/mm/mmap.rs
Original file line number Diff line number Diff line change
Expand Up @@ -345,7 +345,7 @@ pub unsafe fn munlock(ptr: *mut c_void, len: usize) -> io::Result<()> {

/// Locks all pages mapped into the address space of the calling process.
///
/// This includes the pages of the code, data and stack segment, as well as
/// This includes the pages of the code, data, and stack segment, as well as
/// shared libraries, user space kernel data, shared memory, and memory-mapped
/// files. All mapped pages are guaranteed to be resident in RAM when the call
/// returns successfully; the pages are guaranteed to stay in RAM until later
Expand Down
2 changes: 1 addition & 1 deletion src/net/send_recv/msg.rs
Original file line number Diff line number Diff line change
Expand Up @@ -317,7 +317,7 @@ impl<'buf> AncillaryDrain<'buf> {
msg: &c::cmsghdr,
) -> Option<RecvAncillaryMessage<'buf>> {
unsafe {
// Advance the "read" pointer.
// Advance the `read` pointer.
let msg_len = msg.cmsg_len as usize;
*read += msg_len;
*length -= msg_len;
Expand Down
4 changes: 2 additions & 2 deletions src/net/sockopt.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1067,8 +1067,8 @@ pub fn get_ipv6_freebind<Fd: AsFd>(fd: Fd) -> io::Result<bool> {

/// `getsockopt(fd, IPPROTO_IP, SO_ORIGINAL_DST)`
///
/// Even though this corresponnds to a `SO_*` constant, it is an
/// `IPPROTO_IP` option.
/// Even though this corresponnds to a `SO_*` constant, it is an `IPPROTO_IP`
/// option.
///
/// See the [module-level documentation] for more.
///
Expand Down
6 changes: 3 additions & 3 deletions src/pipe.rs
Original file line number Diff line number Diff line change
Expand Up @@ -156,9 +156,9 @@ pub fn splice<FdIn: AsFd, FdOut: AsFd>(
/// the pipe is placed in `fd`.
///
/// Additionally if `SpliceFlags::GIFT` is set, the caller must also ensure
/// that the contents of `bufs` in never modified following the call,
/// and that all of the pointers in `bufs` are page aligned,
/// and the lengths are multiples of a page size in bytes.
/// that the contents of `bufs` in never modified following the call, and that
/// all of the pointers in `bufs` are page aligned, and the lengths are
/// multiples of a page size in bytes.
///
/// # References
/// - [Linux]
Expand Down
8 changes: 5 additions & 3 deletions src/process/chdir.rs
Original file line number Diff line number Diff line change
Expand Up @@ -67,13 +67,15 @@ fn _getcwd(mut buffer: Vec<u8>) -> io::Result<CString> {
loop {
match backend::process::syscalls::getcwd(buffer.spare_capacity_mut()) {
Err(io::Errno::RANGE) => {
buffer.reserve(buffer.capacity() + 1); // use `Vec` reallocation strategy to grow capacity exponentially
// Use `Vec` reallocation strategy to grow capacity
// exponentially.
buffer.reserve(buffer.capacity() + 1);
}
Ok(_) => {
// SAFETY:
// - "These functions return a null-terminated string"
// - [POSIX definition 3.375: String]: "A contiguous sequence of bytes
// terminated by and including the first null byte."
// - [POSIX definition 3.375: String]: "A contiguous sequence
// of bytes terminated by and including the first null byte."
//
// Thus, there will be a single NUL byte at the end of the
// string.
Expand Down
4 changes: 2 additions & 2 deletions src/process/prctl.rs
Original file line number Diff line number Diff line change
Expand Up @@ -764,8 +764,8 @@ pub struct PrctlMmMap {
///
/// # Safety
///
/// Please ensure the conditions necessary to safely call this function,
/// as detailed in the references above.
/// Please ensure the conditions necessary to safely call this function, as
/// detailed in the references above.
///
/// [`prctl(PR_SET_MM,PR_SET_MM_MAP,...)`]: https://man7.org/linux/man-pages/man2/prctl.2.html
#[inline]
Expand Down
Loading

0 comments on commit ce11b6c

Please sign in to comment.