diff options
author | Sachin Cherian <sachinctl@protonmail.com> | 2021-12-03 16:27:44 +0530 |
---|---|---|
committer | Sachin Cherian <sachinctl@protonmail.com> | 2021-12-03 16:27:44 +0530 |
commit | 584d5a5d5108a155391d5e0a97b0a0b1e891c9a2 (patch) | |
tree | 63e6dd602e6d8166431a5d104e65772321589872 | |
parent | 055818a5f4f678e8a075604d990d60e6a99f08d8 (diff) | |
download | nix-584d5a5d5108a155391d5e0a97b0a0b1e891c9a2.zip |
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
-rw-r--r-- | src/sys/memfd.rs | 28 | ||||
-rw-r--r-- | src/sys/mman.rs | 59 | ||||
-rw-r--r-- | src/sys/mod.rs | 1 |
3 files changed, 70 insertions, 18 deletions
diff --git a/src/sys/memfd.rs b/src/sys/memfd.rs index 0236eef6..642676b4 100644 --- a/src/sys/memfd.rs +++ b/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()) 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| { diff --git a/src/sys/mod.rs b/src/sys/mod.rs index a87de55b..156b0d9d 100644 --- a/src/sys/mod.rs +++ b/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"))] |