Merge #1653

1653: Document inotify, mman, personality, reboot, timerfd r=asomers a=rtzoeller

Document the `inotify`, `mman`, `personality`, `reboot`, and `timerfd` modules.

Co-authored-by: Ryan Zoeller <[email protected]>

Author: bors[bot]

src/sys/inotify.rs

@@ -41,39 +41,63 @@ use cfg_if::cfg_if;
 libc_bitflags! {
     /// Configuration options for [`inotify_add_watch`](fn.inotify_add_watch.html).
     pub struct AddWatchFlags: u32 {
+        /// File was accessed.
         IN_ACCESS;
+        /// File was modified.
         IN_MODIFY;
+        /// Metadata changed.
         IN_ATTRIB;
+        /// Writable file was closed.
         IN_CLOSE_WRITE;
+        /// Nonwritable file was closed.
         IN_CLOSE_NOWRITE;
+        /// File was opened.
         IN_OPEN;
+        /// File was moved from X.
         IN_MOVED_FROM;
+        /// File was moved to Y.
         IN_MOVED_TO;
+        /// Subfile was created.
         IN_CREATE;
+        /// Subfile was deleted.
         IN_DELETE;
+        /// Self was deleted.
         IN_DELETE_SELF;
+        /// Self was moved.
         IN_MOVE_SELF;
 
+        /// Backing filesystem was unmounted.
         IN_UNMOUNT;
+        /// Event queue overflowed.
         IN_Q_OVERFLOW;
+        /// File was ignored.
         IN_IGNORED;
 
+        /// Combination of `IN_CLOSE_WRITE` and `IN_CLOSE_NOWRITE`.
         IN_CLOSE;
+        /// Combination of `IN_MOVED_FROM` and `IN_MOVED_TO`.
         IN_MOVE;
 
+        /// Only watch the path if it is a directory.
         IN_ONLYDIR;
+        /// Don't follow symlinks.
         IN_DONT_FOLLOW;
 
+        /// Event occurred against directory.
         IN_ISDIR;
+        /// Only send event once.
         IN_ONESHOT;
+        /// All of the events.
         IN_ALL_EVENTS;
     }
 }
 
 libc_bitflags! {
     /// Configuration options for [`inotify_init1`](fn.inotify_init1.html).
     pub struct InitFlags: c_int {
+        /// Set the `FD_CLOEXEC` flag on the file descriptor.
         IN_CLOEXEC;
+        /// Set the `O_NONBLOCK` flag on the open file description referred to by the new file descriptor.
         IN_NONBLOCK;
     }
 }

src/sys/mman.rs

@@ -299,6 +299,7 @@ libc_enum!{
         #[cfg(any(target_os = "dragonfly", target_os = "freebsd"))]
         #[cfg_attr(docsrs, doc(cfg(all())))]
         MADV_CORE,
+        /// This process should not be killed when swap space is exhausted.
         #[cfg(any(target_os = "freebsd"))]
         #[cfg_attr(docsrs, doc(cfg(all())))]
         MADV_PROTECT,
@@ -314,14 +315,18 @@ libc_enum!{
         #[cfg(any(target_os = "ios", target_os = "macos"))]
         #[cfg_attr(docsrs, doc(cfg(all())))]
         MADV_ZERO_WIRED_PAGES,
+        /// Pages can be reused (by anyone).
         #[cfg(any(target_os = "ios", target_os = "macos"))]
         #[cfg_attr(docsrs, doc(cfg(all())))]
         MADV_FREE_REUSABLE,
+        /// Caller wants to reuse those pages.
         #[cfg(any(target_os = "ios", target_os = "macos"))]
         #[cfg_attr(docsrs, doc(cfg(all())))]
         MADV_FREE_REUSE,
+        // Darwin doesn't document this flag's behavior.
         #[cfg(any(target_os = "ios", target_os = "macos"))]
         #[cfg_attr(docsrs, doc(cfg(all())))]
+        #[allow(missing_docs)]
         MADV_CAN_REUSE,
     }
 }

src/sys/mod.rs

@@ -55,14 +55,12 @@ feature! {
 #[cfg(not(target_os = "redox"))]
 feature! {
     #![feature = "mman"]
-    #[allow(missing_docs)]
     pub mod mman;
 }
 
 #[cfg(target_os = "linux")]
 feature! {
     #![feature = "personality"]
-    #[allow(missing_docs)]
     pub mod personality;
 }
 
@@ -93,7 +91,6 @@ feature! {
 #[cfg(target_os = "linux")]
 feature! {
     #![feature = "reboot"]
-    #[allow(missing_docs)]
     pub mod reboot;
 }
 
@@ -192,14 +189,12 @@ feature! {
 #[cfg(any(target_os = "android", target_os = "linux"))]
 feature! {
     #![feature = "inotify"]
-    #[allow(missing_docs)]
     pub mod inotify;
 }
 
 #[cfg(any(target_os = "android", target_os = "linux"))]
 feature! {
     #![feature = "time"]
-    #[allow(missing_docs)]
     pub mod timerfd;
 }
 

src/sys/personality.rs

@@ -1,3 +1,4 @@
+//! Process execution domains
 use crate::Result;
 use crate::errno::Errno;
 
@@ -7,18 +8,44 @@ libc_bitflags! {
     /// Flags used and returned by [`get()`](fn.get.html) and
     /// [`set()`](fn.set.html).
     pub struct Persona: c_int {
+        /// Provide the legacy virtual address space layout.
         ADDR_COMPAT_LAYOUT;
+        /// Disable address-space-layout randomization.
         ADDR_NO_RANDOMIZE;
+        /// Limit the address space to 32 bits.
         ADDR_LIMIT_32BIT;
+        /// Use `0xc0000000` as the offset at which to search a virtual memory
+        /// chunk on [`mmap(2)`], otherwise use `0xffffe000`.
+        ///
+        /// [`mmap(2)`]: https://man7.org/linux/man-pages/man2/mmap.2.html
         ADDR_LIMIT_3GB;
+        /// User-space function pointers to signal handlers point to descriptors.
         #[cfg(not(any(target_env = "musl", target_env = "uclibc")))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         FDPIC_FUNCPTRS;
+        /// Map page 0 as read-only.
         MMAP_PAGE_ZERO;
+        /// `PROT_READ` implies `PROT_EXEC` for [`mmap(2)`].
+        ///
+        /// [`mmap(2)`]: https://man7.org/linux/man-pages/man2/mmap.2.html
         READ_IMPLIES_EXEC;
+        /// No effects.
         SHORT_INODE;
+        /// [`select(2)`], [`pselect(2)`], and [`ppoll(2)`] do not modify the
+        /// returned timeout argument when interrupted by a signal handler.
+        ///
+        /// [`select(2)`]: https://man7.org/linux/man-pages/man2/select.2.html
+        /// [`pselect(2)`]: https://man7.org/linux/man-pages/man2/pselect.2.html
+        /// [`ppoll(2)`]: https://man7.org/linux/man-pages/man2/ppoll.2.html
         STICKY_TIMEOUTS;
+        /// Have [`uname(2)`] report a 2.6.40+ version number rather than a 3.x
+        /// version number.
+        ///
+        /// [`uname(2)`]: https://man7.org/linux/man-pages/man2/uname.2.html
         #[cfg(not(any(target_env = "musl", target_env = "uclibc")))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         UNAME26;
+        /// No effects.
         WHOLE_SECONDS;
     }
 }

src/sys/reboot.rs

@@ -13,15 +13,22 @@ libc_enum! {
     #[repr(i32)]
     #[non_exhaustive]
     pub enum RebootMode {
+        /// Halt the system.
         RB_HALT_SYSTEM,
+        /// Execute a kernel that has been loaded earlier with
+        /// [`kexec_load(2)`](https://man7.org/linux/man-pages/man2/kexec_load.2.html).
         RB_KEXEC,
+        /// Stop the system and switch off power, if possible.
         RB_POWER_OFF,
+        /// Restart the system.
         RB_AUTOBOOT,
-        // we do not support Restart2,
+        // we do not support Restart2.
+        /// Suspend the system using software suspend.
         RB_SW_SUSPEND,
     }
 }
 
+/// Reboots or shuts down the system.
 pub fn reboot(how: RebootMode) -> Result<Infallible> {
     unsafe {
         libc::reboot(how as libc::c_int)

src/sys/timerfd.rs

@@ -60,10 +60,19 @@ libc_enum! {
     #[repr(i32)]
     #[non_exhaustive]
     pub enum ClockId {
+        /// A settable system-wide real-time clock.
         CLOCK_REALTIME,
+        /// A non-settable monotonically increasing clock.
+        ///
+        /// Does not change after system startup.
+        /// Does not measure time while the system is suspended.
         CLOCK_MONOTONIC,
+        /// Like `CLOCK_MONOTONIC`, except that `CLOCK_BOOTTIME` includes the time
+        /// that the system was suspended.
         CLOCK_BOOTTIME,
+        /// Like `CLOCK_REALTIME`, but will wake the system if it is suspended.
         CLOCK_REALTIME_ALARM,
+        /// Like `CLOCK_BOOTTIME`, but will wake the system if it is suspended.
         CLOCK_BOOTTIME_ALARM,
     }
 }
@@ -72,7 +81,9 @@ libc_bitflags! {
     /// Additional flags to change the behaviour of the file descriptor at the
     /// time of creation.
     pub struct TimerFlags: c_int {
+        /// Set the `O_NONBLOCK` flag on the open file description referred to by the new file descriptor.
         TFD_NONBLOCK;
+        /// Set the `FD_CLOEXEC` flag on the file descriptor.
         TFD_CLOEXEC;
     }
 }