From 584d5a5d5108a155391d5e0a97b0a0b1e891c9a2 Mon Sep 17 00:00:00 2001 From: Sachin Cherian Date: Fri, 3 Dec 2021 16:27:44 +0530 Subject: 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 --- src/sys/mman.rs | 59 ++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 42 insertions(+), 17 deletions(-) (limited to 'src/sys/mman.rs') 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(name: &P, flag: OFlag, mode: Mode) -> Result { let ret = name.with_nix_path(|cstr| { @@ -454,6 +474,11 @@ pub fn shm_open(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(name: &P) -> Result<()> { let ret = name.with_nix_path(|cstr| { -- cgit v1.2.3