Update `mman` related docs

- Add docs for `memfd_create`, `shm_open`, and `shm_unlink`
- Add man-page links
- Remove` #[allow(missing_docs)]`on the `memfd` module

1 files changed, 42 insertions, 17 deletions

diff --git a/src/sys/mman.rs b/src/sys/mman.rs
index 882a2b94..e8577685 100644
--- a/src/sys/mman.rs
+++ b/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| {