Merge #1759 #1760

1759: More docs for dir and mqueue r=rtzoeller a=asomers

Add doc comments for the `dir` and `mqueue` modules.  Also, delete dead code in `mqueue`

1760: Add const constructors for TimeSpec and TimeVal r=rtzoeller a=asomers

These are basically the same as From<libc::timespec> and
From<libc::timeval>, but they're const and require less typing.

Co-authored-by: Alan Somers <[email protected]>

CHANGELOG.md

@@ -6,9 +6,10 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 ## [Unreleased] - ReleaseDate
 ### Added
 
+- Added const constructors for `TimeSpec` and `TimeVal`
+  (#[1760](https://github.com/nix-rust/nix/pull/1760))
 - Added `aio_writev` and `aio_readv`.
   (#[1713](https://github.com/nix-rust/nix/pull/1713))
-
 - impl `From<uid_t>` for `Uid` and `From<gid_t>` for `Gid`
   (#[1727](https://github.com/nix-rust/nix/pull/1727))
 - impl From<SockaddrIn> for std::net::SocketAddrV4 and

src/dir.rs

@@ -1,3 +1,5 @@
+//! List directory contents
+
 use crate::{Error, NixPath, Result};
 use crate::errno::Errno;
 use crate::fcntl::{self, OFlag};
@@ -114,6 +116,7 @@ fn next(dir: &mut Dir) -> Option<Result<Entry>> {
     }
 }
 
+/// Return type of [`Dir::iter`].
 #[derive(Debug, Eq, Hash, PartialEq)]
 pub struct Iter<'d>(&'d mut Dir);
 
@@ -183,14 +186,22 @@ impl IntoIterator for Dir {
 #[repr(transparent)]
 pub struct Entry(dirent);
 
+/// Type of file referenced by a directory entry
 #[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
 pub enum Type {
+    /// FIFO (Named pipe)
     Fifo,
+    /// Character device
     CharacterDevice,
+    /// Directory
     Directory,
+    /// Block device
     BlockDevice,
+    /// Regular file
     File,
+    /// Symbolic link
     Symlink,
+    /// Unix-domain socket
     Socket,
 }
 

src/lib.rs

@@ -65,7 +65,6 @@ mod macros;
 #[cfg(not(target_os = "redox"))]
 feature! {
     #![feature = "dir"]
-    #[allow(missing_docs)]
     pub mod dir;
 }
 feature! {
@@ -119,7 +118,6 @@ feature! {
 ))]
 feature! {
     #![feature = "mqueue"]
-    #[allow(missing_docs)]
     pub mod mqueue;
 }
 feature! {

src/mqueue.rs

@@ -39,23 +39,29 @@ use crate::sys::stat::Mode;
 use std::mem;
 
 libc_bitflags!{
+    /// Used with [`mq_open`].
     pub struct MQ_OFlag: libc::c_int {
+        /// Open the message queue for receiving messages.
         O_RDONLY;
+        /// Open the queue for sending messages.
         O_WRONLY;
+        /// Open the queue for both receiving and sending messages
         O_RDWR;
+        /// Create a message queue.
         O_CREAT;
+        /// If set along with `O_CREAT`, `mq_open` will fail if the message
+        /// queue name exists.
         O_EXCL;
+        /// `mq_send` and `mq_receive` should fail with `EAGAIN` rather than
+        /// wait for resources that are not currently available.
         O_NONBLOCK;
+        /// Set the close-on-exec flag for the message queue descriptor.
         O_CLOEXEC;
     }
 }
 
-libc_bitflags!{
-    pub struct FdFlag: libc::c_int {
-        FD_CLOEXEC;
-    }
-}
-
+/// A message-queue attribute, optionally used with [`mq_setattr`] and
+/// [`mq_getattr`] and optionally [`mq_open`],
 #[repr(C)]
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 pub struct MqAttr {
@@ -72,14 +78,24 @@ pub struct MqdT(mqd_t);
 
 // x32 compatibility
 // See https://sourceware.org/bugzilla/show_bug.cgi?id=21279
+/// Size of a message queue attribute member
 #[cfg(all(target_arch = "x86_64", target_pointer_width = "32"))]
 #[cfg_attr(docsrs, doc(cfg(all())))]
 pub type mq_attr_member_t = i64;
+/// Size of a message queue attribute member
 #[cfg(not(all(target_arch = "x86_64", target_pointer_width = "32")))]
 #[cfg_attr(docsrs, doc(cfg(all())))]
 pub type mq_attr_member_t = libc::c_long;
 
 impl MqAttr {
+    /// Create a new message queue attribute
+    ///
+    /// # Arguments
+    ///
+    /// - `mq_flags`:   Either `0` or `O_NONBLOCK`.
+    /// - `mq_maxmsg`:  Maximum number of messages on the queue.
+    /// - `mq_msgsize`: Maximum message size in bytes.
+    /// - `mq_curmsgs`: Number of messages currently in the queue.
     pub fn new(mq_flags: mq_attr_member_t,
                mq_maxmsg: mq_attr_member_t,
                mq_msgsize: mq_attr_member_t,
@@ -97,6 +113,7 @@ impl MqAttr {
         }
     }
 
+    /// The current flags, either `0` or `O_NONBLOCK`.
     pub const fn flags(&self) -> mq_attr_member_t {
         self.mq_attr.mq_flags
     }

src/sys/time.rs

@@ -330,6 +330,15 @@ impl TimeValLike for TimeSpec {
 }
 
 impl TimeSpec {
+    /// Construct a new `TimeSpec` from its components
+    #[cfg_attr(target_env = "musl", allow(deprecated))] // https://github.com/rust-lang/libc/issues/1848
+    pub const fn new(seconds: time_t, nanoseconds: timespec_tv_nsec_t) -> Self {
+        Self(timespec {
+            tv_sec: seconds,
+            tv_nsec: nanoseconds,
+        })
+    }
+
     fn nanos_mod_sec(&self) -> timespec_tv_nsec_t {
         if self.tv_sec() < 0 && self.tv_nsec() > 0 {
             self.tv_nsec() - NANOS_PER_SEC as timespec_tv_nsec_t
@@ -564,6 +573,15 @@ impl TimeValLike for TimeVal {
 }
 
 impl TimeVal {
+    /// Construct a new `TimeVal` from its components
+    #[cfg_attr(target_env = "musl", allow(deprecated))] // https://github.com/rust-lang/libc/issues/1848
+    pub const fn new(seconds: time_t, microseconds: suseconds_t) -> Self {
+        Self(timeval {
+            tv_sec: seconds,
+            tv_usec: microseconds,
+        })
+    }
+
     fn micros_mod_sec(&self) -> suseconds_t {
         if self.tv_sec() < 0 && self.tv_usec() > 0 {
             self.tv_usec() - MICROS_PER_SEC as suseconds_t