Merge #1601

1601: Update `mman` related docs r=rtzoeller a=schctl

Added docs for `memfd_create`, `shm_open`, and `shm_unlink`, and some man-page and intra doc links.

Co-authored-by: Sachin Cherian <sachinctl@protonmail.com>

Author: bors[bot]

src/sys/memfd.rs

@@ -1,15 +1,43 @@
+//! Interfaces for managing memory-backed files.
+
 use std::os::unix::io::RawFd;
 use crate::Result;
 use crate::errno::Errno;
 use std::ffi::CStr;
 
 libc_bitflags!(
+    /// Options that change the behavior of [`memfd_create`].
     pub struct MemFdCreateFlag: libc::c_uint {
+        /// Set the close-on-exec ([`FD_CLOEXEC`]) flag on the new file descriptor.
+        ///
+        /// By default, the new file descriptor is set to remain open across an [`execve`]
+        /// (the `FD_CLOEXEC` flag is initially disabled). This flag can be used to change
+        /// this default. The file offset is set to the beginning of the file (see [`lseek`]).
+        ///
+        /// See also the description of the `O_CLOEXEC` flag in [`open(2)`].
+        ///
+        /// [`execve`]: crate::unistd::execve
+        /// [`lseek`]: crate::unistd::lseek
+        /// [`FD_CLOEXEC`]: crate::fcntl::FdFlag::FD_CLOEXEC
+        /// [`open(2)`]: https://man7.org/linux/man-pages/man2/open.2.html
         MFD_CLOEXEC;
+        /// Allow sealing operations on this file.
+        ///
+        /// See also the file sealing notes given in [`memfd_create(2)`].
+        ///
+        /// [`memfd_create(2)`]: https://man7.org/linux/man-pages/man2/memfd_create.2.html
         MFD_ALLOW_SEALING;
     }
 );
 
+/// Creates an anonymous file that lives in memory, and return a file-descriptor to it.
+///
+/// The file behaves like a regular file, and so can be modified, truncated, memory-mapped, and so on.
+/// However, unlike a regular file, it lives in RAM and has a volatile backing storage.
+///
+/// For more information, see [`memfd_create(2)`].
+///
+/// [`memfd_create(2)`]: https://man7.org/linux/man-pages/man2/memfd_create.2.html
 pub fn memfd_create(name: &CStr, flags: MemFdCreateFlag) -> Result<RawFd> {
     let res = unsafe {
         libc::syscall(libc::SYS_memfd_create, name.as_ptr(), flags.bits())

src/sys/mman.rs

@@ -1,3 +1,5 @@
+//! Memory management declarations.
+
 use crate::Result;
 #[cfg(not(target_os = "android"))]
 use crate::NixPath;
@@ -30,7 +32,7 @@ libc_bitflags!{
 }
 
 libc_bitflags!{
-    /// Additional parameters for `mmap()`.
+    /// Additional parameters for [`mmap`].
     pub struct MapFlags: c_int {
         /// Compatibility flag. Ignored.
         MAP_FILE;
@@ -151,7 +153,7 @@ libc_bitflags!{
 
 #[cfg(any(target_os = "linux", target_os = "netbsd"))]
 libc_bitflags!{
-    /// Options for `mremap()`.
+    /// Options for [`mremap`].
     pub struct MRemapFlags: c_int {
         /// Permit the kernel to relocate the mapping to a new virtual address, if necessary.
         #[cfg(target_os = "linux")]
@@ -171,7 +173,7 @@ libc_bitflags!{
 libc_enum!{
     /// Usage information for a range of memory to allow for performance optimizations by the kernel.
     ///
-    /// Used by [`madvise`](./fn.madvise.html).
+    /// Used by [`madvise`].
     #[repr(i32)]
     #[non_exhaustive]
     pub enum MmapAdvise {
@@ -264,7 +266,7 @@ libc_enum!{
 }
 
 libc_bitflags!{
-    /// Configuration flags for `msync`.
+    /// Configuration flags for [`msync`].
     pub struct MsFlags: c_int {
         /// Schedule an update but return immediately.
         MS_ASYNC;
@@ -282,7 +284,7 @@ libc_bitflags!{
 }
 
 libc_bitflags!{
-    /// Flags for `mlockall`.
+    /// Flags for [`mlockall`].
     pub struct MlockAllFlags: c_int {
         /// Lock pages that are currently mapped into the address space of the process.
         MCL_CURRENT;
@@ -298,7 +300,9 @@ libc_bitflags!{
 ///
 /// # Safety
 ///
-/// `addr` must meet all the requirements described in the `mlock(2)` man page.
+/// `addr` must meet all the requirements described in the [`mlock(2)`] man page.
+///
+/// [`mlock(2)`]: https://man7.org/linux/man-pages/man2/mlock.2.html
 pub unsafe fn mlock(addr: *const c_void, length: size_t) -> Result<()> {
     Errno::result(libc::mlock(addr, length)).map(drop)
 }
@@ -308,25 +312,28 @@ pub unsafe fn mlock(addr: *const c_void, length: size_t) -> Result<()> {
 ///
 /// # Safety
 ///
-/// `addr` must meet all the requirements described in the `munlock(2)` man
+/// `addr` must meet all the requirements described in the [`munlock(2)`] man
 /// page.
+///
+/// [`munlock(2)`]: https://man7.org/linux/man-pages/man2/munlock.2.html
 pub unsafe fn munlock(addr: *const c_void, length: size_t) -> Result<()> {
     Errno::result(libc::munlock(addr, length)).map(drop)
 }
 
 /// Locks all memory pages mapped into this process' address space.
 ///
-/// Locked pages never move to the swap area.
+/// Locked pages never move to the swap area. For more information, see [`mlockall(2)`].
 ///
-/// # Safety
-///
-/// `addr` must meet all the requirements described in the `mlockall(2)` man
-/// page.
+/// [`mlockall(2)`]: https://man7.org/linux/man-pages/man2/mlockall.2.html
 pub fn mlockall(flags: MlockAllFlags) -> Result<()> {
     unsafe { Errno::result(libc::mlockall(flags.bits())) }.map(drop)
 }
 
 /// Unlocks all memory pages mapped into this process' address space.
+///
+/// For more information, see [`munlockall(2)`].
+///
+/// [`munlockall(2)`]: https://man7.org/linux/man-pages/man2/munlockall.2.html
 pub fn munlockall() -> Result<()> {
     unsafe { Errno::result(libc::munlockall()) }.map(drop)
 }
@@ -335,7 +342,9 @@ pub fn munlockall() -> Result<()> {
 ///
 /// # Safety
 ///
-/// See the `mmap(2)` man page for detailed requirements.
+/// See the [`mmap(2)`] man page for detailed requirements.
+///
+/// [`mmap(2)`]: https://man7.org/linux/man-pages/man2/mmap.2.html
 pub unsafe fn mmap(addr: *mut c_void, length: size_t, prot: ProtFlags, flags: MapFlags, fd: RawFd, offset: off_t) -> Result<*mut c_void> {
     let ret = libc::mmap(addr, length, prot.bits(), flags.bits(), fd, offset);
 
@@ -383,8 +392,10 @@ pub unsafe fn mremap(
 ///
 /// # Safety
 ///
-/// `addr` must meet all the requirements described in the `munmap(2)` man
+/// `addr` must meet all the requirements described in the [`munmap(2)`] man
 /// page.
+///
+/// [`munmap(2)`]: https://man7.org/linux/man-pages/man2/munmap.2.html
 pub unsafe fn munmap(addr: *mut c_void, len: size_t) -> Result<()> {
     Errno::result(libc::munmap(addr, len)).map(drop)
 }
@@ -393,8 +404,10 @@ pub unsafe fn munmap(addr: *mut c_void, len: size_t) -> Result<()> {
 ///
 /// # Safety
 ///
-/// See the `madvise(2)` man page.  Take special care when using
-/// `MmapAdvise::MADV_FREE`.
+/// See the [`madvise(2)`] man page.  Take special care when using
+/// [`MmapAdvise::MADV_FREE`].
+///
+/// [`madvise(2)`]: https://man7.org/linux/man-pages/man2/madvise.2.html
 pub unsafe fn madvise(addr: *mut c_void, length: size_t, advise: MmapAdvise) -> Result<()> {
     Errno::result(libc::madvise(addr, length, advise as i32)).map(drop)
 }
@@ -432,12 +445,19 @@ pub unsafe fn mprotect(addr: *mut c_void, length: size_t, prot: ProtFlags) -> Re
 ///
 /// # Safety
 ///
-/// `addr` must meet all the requirements described in the `msync(2)` man
+/// `addr` must meet all the requirements described in the [`msync(2)`] man
 /// page.
+///
+/// [`msync(2)`]: https://man7.org/linux/man-pages/man2/msync.2.html
 pub unsafe fn msync(addr: *mut c_void, length: size_t, flags: MsFlags) -> Result<()> {
     Errno::result(libc::msync(addr, length, flags.bits())).map(drop)
 }
 
+/// Creates and opens a new, or opens an existing, POSIX shared memory object.
+///
+/// For more information, see [`shm_open(3)`].
+///
+/// [`shm_open(3)`]: https://man7.org/linux/man-pages/man3/shm_open.3.html
 #[cfg(not(target_os = "android"))]
 pub fn shm_open<P: ?Sized + NixPath>(name: &P, flag: OFlag, mode: Mode) -> Result<RawFd> {
     let ret = name.with_nix_path(|cstr| {
@@ -454,6 +474,11 @@ pub fn shm_open<P: ?Sized + NixPath>(name: &P, flag: OFlag, mode: Mode) -> Resul
     Errno::result(ret)
 }
 
+/// Performs the converse of [`shm_open`], removing an object previously created.
+///
+/// For more information, see [`shm_unlink(3)`].
+///
+/// [`shm_unlink(3)`]: https://man7.org/linux/man-pages/man3/shm_unlink.3.html
 #[cfg(not(target_os = "android"))]
 pub fn shm_unlink<P: ?Sized + NixPath>(name: &P) -> Result<()> {
     let ret = name.with_nix_path(|cstr| {

src/sys/mod.rs

@@ -38,7 +38,6 @@ pub mod eventfd;
 pub mod ioctl;
 
 #[cfg(target_os = "linux")]
-#[allow(missing_docs)]
 pub mod memfd;
 
 #[cfg(not(target_os = "redox"))]