From eaec1d55d4bfe7d2c2ac82a1b1329b8b81a60e55 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Mon, 11 Sep 2023 06:02:28 -0700 Subject: [PATCH] Miscellaneous documentation cleanups. --- src/fs/fd.rs | 4 ++-- src/fs/statx.rs | 2 +- src/ioctl/mod.rs | 2 +- src/runtime.rs | 9 ++++++--- src/termios/tty.rs | 3 ++- 5 files changed, 12 insertions(+), 8 deletions(-) diff --git a/src/fs/fd.rs b/src/fs/fd.rs index 43b2e57b1..de49c97f8 100644 --- a/src/fs/fd.rs +++ b/src/fs/fd.rs @@ -105,7 +105,7 @@ pub fn tell(fd: Fd) -> io::Result { backend::fs::syscalls::tell(fd.as_fd()) } -/// `fchmod(fd)`—Sets open file or directory permissions. +/// `fchmod(fd, mode)`—Sets open file or directory permissions. /// /// This implementation does not support `O_PATH` file descriptors, even on /// platforms where the host libc emulates it. @@ -122,7 +122,7 @@ pub fn fchmod(fd: Fd, mode: Mode) -> io::Result<()> { backend::fs::syscalls::fchmod(fd.as_fd(), mode) } -/// `fchown(fd)`—Sets open file or directory ownership. +/// `fchown(fd, owner, group)`—Sets open file or directory ownership. /// /// # References /// - [POSIX] diff --git a/src/fs/statx.rs b/src/fs/statx.rs index 86972384a..1791697af 100644 --- a/src/fs/statx.rs +++ b/src/fs/statx.rs @@ -28,7 +28,7 @@ use compat::statx as _statx; /// # use std::io; /// # use rustix::fs::{AtFlags, StatxFlags}; /// # use rustix::fd::BorrowedFd; -/// /// Try to determine if the provided path is a mount root. Will return `Ok(None)` if +/// /// Try to determine if the provided path is a mount root. Will return `Ok(None)` if /// /// the kernel is not new enough to support statx() or [`libc::STATX_ATTR_MOUNT_ROOT`]. /// fn is_mountpoint(root: BorrowedFd<'_>, path: &Path) -> io::Result> { /// use rustix::fs::{AtFlags, StatxFlags}; diff --git a/src/ioctl/mod.rs b/src/ioctl/mod.rs index aaaf584e2..c9a989bac 100644 --- a/src/ioctl/mod.rs +++ b/src/ioctl/mod.rs @@ -160,7 +160,7 @@ pub unsafe trait Ioctl { /// making this `false` enables optimizations that can make the call /// faster. When in doubt, set this to `true`. /// - /// # SAFETY + /// # Safety /// /// This should only be set to `false` if the `ioctl` call does not mutate /// any data in the userspace. Undefined behavior may occur if this is diff --git a/src/runtime.rs b/src/runtime.rs index afaae5da1..942b69fd4 100644 --- a/src/runtime.rs +++ b/src/runtime.rs @@ -2,8 +2,11 @@ //! [origin]. //! //! Do not use the functions in this module unless you've read all of their -//! code, *and* you know all the relevant internal implementation details of -//! any libc in the process they'll be used. +//! 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 @@ -143,7 +146,7 @@ pub unsafe fn exit_thread(status: i32) -> ! { /// /// This is equivalent to `_exit` and `_Exit` in libc. /// -/// This does not all any `__cxa_atexit`, `atexit`, or any other destructors. +/// This does not call any `__cxa_atexit`, `atexit`, or any other destructors. /// Most programs should use [`std::process::exit`] instead of calling this /// directly. /// diff --git a/src/termios/tty.rs b/src/termios/tty.rs index f66210d08..56aab9fcf 100644 --- a/src/termios/tty.rs +++ b/src/termios/tty.rs @@ -54,7 +54,8 @@ fn _ttyname(dirfd: BorrowedFd<'_>, mut buffer: Vec) -> io::Result { buffer.reserve(buffer.capacity() + 1); // use `Vec` reallocation strategy to grow capacity exponentially } Ok(len) => { - // SAFETY: assume the backend returns the length of the string excluding the NUL. + // SAFETY: assume the backend returns the length of the string excluding the + // NUL. unsafe { buffer.set_len(len + 1); }