diff options
| -rw-r--r-- | src/env.rs | 1 | ||||
| -rw-r--r-- | src/lib.rs | 23 | ||||
| -rw-r--r-- | src/mount/bsd.rs | 1 | ||||
| -rw-r--r-- | src/mount/mod.rs | 3 | ||||
| -rw-r--r-- | src/sched.rs | 55 | ||||
| -rw-r--r-- | src/sys/aio.rs | 4 | ||||
| -rw-r--r-- | src/sys/mod.rs | 26 | ||||
| -rw-r--r-- | src/sys/signal.rs | 2 |
8 files changed, 102 insertions, 13 deletions
@@ -1,3 +1,4 @@ +//! Environment variables use cfg_if::cfg_if; use std::fmt; @@ -5,15 +5,13 @@ #![crate_name = "nix"] #![cfg(unix)] #![allow(non_camel_case_types)] -// latest bitflags triggers a rustc bug with cross-crate macro expansions causing dead_code -// warnings even though the macro expands into something with allow(dead_code) -#![allow(dead_code)] #![cfg_attr(test, deny(warnings))] #![recursion_limit = "500"] #![deny(unused)] #![deny(unstable_features)] #![deny(missing_copy_implementations)] #![deny(missing_debug_implementations)] +#![deny(missing_docs)] // Re-exported external crates pub use libc; @@ -23,13 +21,14 @@ pub use libc; // Public crates #[cfg(not(target_os = "redox"))] +#[allow(missing_docs)] pub mod dir; pub mod env; +#[allow(missing_docs)] pub mod errno; -#[deny(missing_docs)] pub mod features; +#[allow(missing_docs)] pub mod fcntl; -#[deny(missing_docs)] #[cfg(any(target_os = "android", target_os = "dragonfly", target_os = "freebsd", @@ -42,6 +41,7 @@ pub mod fcntl; pub mod ifaddrs; #[cfg(any(target_os = "android", target_os = "linux"))] +#[allow(missing_docs)] pub mod kmod; #[cfg(any(target_os = "android", target_os = "freebsd", @@ -52,23 +52,24 @@ pub mod mount; target_os = "fushsia", target_os = "linux", target_os = "netbsd"))] +#[allow(missing_docs)] pub mod mqueue; -#[deny(missing_docs)] #[cfg(not(target_os = "redox"))] pub mod net; -#[deny(missing_docs)] pub mod poll; -#[deny(missing_docs)] #[cfg(not(any(target_os = "redox", target_os = "fuchsia")))] pub mod pty; pub mod sched; pub mod sys; +#[allow(missing_docs)] pub mod time; // This can be implemented for other platforms as soon as libc // provides bindings for them. #[cfg(all(target_os = "linux", any(target_arch = "x86", target_arch = "x86_64")))] +#[allow(missing_docs)] pub mod ucontext; +#[allow(missing_docs)] pub mod unistd; /* @@ -101,11 +102,17 @@ pub type Result<T> = result::Result<T, Errno>; /// ones. pub type Error = Errno; +/// Common trait used to represent file system paths by many Nix functions. pub trait NixPath { + /// Is the path empty? fn is_empty(&self) -> bool; + /// Length of the path in bytes fn len(&self) -> usize; + /// Execute a function with this path as a `CStr`. + /// + /// Mostly used internally by Nix. fn with_nix_path<T, F>(&self, f: F) -> Result<T> where F: FnOnce(&CStr) -> T; } diff --git a/src/mount/bsd.rs b/src/mount/bsd.rs index f0a9443a..9913fc20 100644 --- a/src/mount/bsd.rs +++ b/src/mount/bsd.rs @@ -347,6 +347,7 @@ impl<'a> Nmount<'a> { self } + /// Create a new `Nmount` struct with no options pub fn new() -> Self { Self::default() } diff --git a/src/mount/mod.rs b/src/mount/mod.rs index 8538bf3d..00303b6a 100644 --- a/src/mount/mod.rs +++ b/src/mount/mod.rs @@ -1,7 +1,10 @@ +//! Mount file systems #[cfg(any(target_os = "android", target_os = "linux"))] +#[allow(missing_docs)] mod linux; #[cfg(any(target_os = "android", target_os = "linux"))] +#[allow(missing_docs)] pub use self::linux::*; #[cfg(any(target_os = "dragonfly", diff --git a/src/sched.rs b/src/sched.rs index 575bf24b..69436fdf 100644 --- a/src/sched.rs +++ b/src/sched.rs @@ -1,3 +1,7 @@ +//! Execution scheduling +//! +//! See Also +//! [sched.h](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sched.h.html) use crate::{Errno, Result}; #[cfg(any(target_os = "android", target_os = "linux"))] @@ -16,33 +20,70 @@ mod sched_linux_like { // For some functions taking with a parameter of type CloneFlags, // only a subset of these flags have an effect. libc_bitflags! { + /// Options for use with [`clone`] pub struct CloneFlags: c_int { + /// The calling process and the child process run in the same + /// memory space. CLONE_VM; + /// The caller and the child process share the same filesystem + /// information. CLONE_FS; + /// The calling process and the child process share the same file + /// descriptor table. CLONE_FILES; + /// The calling process and the child process share the same table + /// of signal handlers. CLONE_SIGHAND; + /// If the calling process is being traced, then trace the child + /// also. CLONE_PTRACE; + /// The execution of the calling process is suspended until the + /// child releases its virtual memory resources via a call to + /// execve(2) or _exit(2) (as with vfork(2)). CLONE_VFORK; + /// The parent of the new child (as returned by getppid(2)) + /// will be the same as that of the calling process. CLONE_PARENT; + /// The child is placed in the same thread group as the calling + /// process. CLONE_THREAD; + /// The cloned child is started in a new mount namespace. CLONE_NEWNS; + /// The child and the calling process share a single list of System + /// V semaphore adjustment values CLONE_SYSVSEM; - CLONE_SETTLS; - CLONE_PARENT_SETTID; - CLONE_CHILD_CLEARTID; + // Not supported by Nix due to lack of varargs support in Rust FFI + // CLONE_SETTLS; + // Not supported by Nix due to lack of varargs support in Rust FFI + // CLONE_PARENT_SETTID; + // Not supported by Nix due to lack of varargs support in Rust FFI + // CLONE_CHILD_CLEARTID; + /// Unused since Linux 2.6.2 + #[deprecated(since = "0.23.0", note = "Deprecated by Linux 2.6.2")] CLONE_DETACHED; + /// A tracing process cannot force `CLONE_PTRACE` on this child + /// process. CLONE_UNTRACED; - CLONE_CHILD_SETTID; + // Not supported by Nix due to lack of varargs support in Rust FFI + // CLONE_CHILD_SETTID; + /// Create the process in a new cgroup namespace. CLONE_NEWCGROUP; + /// Create the process in a new UTS namespace. CLONE_NEWUTS; + /// Create the process in a new IPC namespace. CLONE_NEWIPC; + /// Create the process in a new user namespace. CLONE_NEWUSER; + /// Create the process in a new PID namespace. CLONE_NEWPID; + /// Create the process in a new network namespace. CLONE_NEWNET; + /// The new process shares an I/O context with the calling process. CLONE_IO; } } + /// Type for the function executed by [`clone`]. pub type CloneCb<'a> = Box<dyn FnMut() -> isize + 'a>; /// CpuSet represent a bit-mask of CPUs. @@ -212,12 +253,18 @@ mod sched_linux_like { Errno::result(res).map(Pid::from_raw) } + /// disassociate parts of the process execution context + /// + /// See also [unshare(2)](https://man7.org/linux/man-pages/man2/unshare.2.html) pub fn unshare(flags: CloneFlags) -> Result<()> { let res = unsafe { libc::unshare(flags.bits()) }; Errno::result(res).map(drop) } + /// reassociate thread with a namespace + /// + /// See also [setns(2)](https://man7.org/linux/man-pages/man2/setns.2.html) pub fn setns(fd: RawFd, nstype: CloneFlags) -> Result<()> { let res = unsafe { libc::setns(fd, nstype.bits()) }; diff --git a/src/sys/aio.rs b/src/sys/aio.rs index 71a2184d..ae08a1fc 100644 --- a/src/sys/aio.rs +++ b/src/sys/aio.rs @@ -60,8 +60,11 @@ libc_enum! { #[repr(i32)] #[non_exhaustive] pub enum LioOpcode { + /// No operation LIO_NOP, + /// Write data as if by a call to [`aio_write`] LIO_WRITE, + /// Write data as if by a call to [`aio_read`] LIO_READ, } } @@ -840,6 +843,7 @@ unsafe impl<'a> Sync for LioCb<'a> {} #[cfg(not(any(target_os = "ios", target_os = "macos")))] impl<'a> LioCb<'a> { + /// Are no [`AioCb`]s contained? pub fn is_empty(&self) -> bool { self.aiocbs.is_empty() } diff --git a/src/sys/mod.rs b/src/sys/mod.rs index cffefdc3..2f356801 100644 --- a/src/sys/mod.rs +++ b/src/sys/mod.rs @@ -1,3 +1,4 @@ +//! Mostly platform-specific functionality #[cfg(any(target_os = "dragonfly", target_os = "freebsd", target_os = "ios", @@ -7,6 +8,7 @@ pub mod aio; #[cfg(any(target_os = "android", target_os = "linux"))] +#[allow(missing_docs)] pub mod epoll; #[cfg(any(target_os = "dragonfly", @@ -15,9 +17,11 @@ pub mod epoll; target_os = "macos", target_os = "netbsd", target_os = "openbsd"))] +#[allow(missing_docs)] pub mod event; #[cfg(any(target_os = "android", target_os = "linux"))] +#[allow(missing_docs)] pub mod eventfd; #[cfg(any(target_os = "android", @@ -34,14 +38,18 @@ pub mod eventfd; pub mod ioctl; #[cfg(target_os = "linux")] +#[allow(missing_docs)] pub mod memfd; #[cfg(not(target_os = "redox"))] +#[allow(missing_docs)] pub mod mman; #[cfg(target_os = "linux")] +#[allow(missing_docs)] pub mod personality; +#[allow(missing_docs)] pub mod pthread; #[cfg(any(target_os = "android", @@ -51,18 +59,22 @@ pub mod pthread; target_os = "macos", target_os = "netbsd", target_os = "openbsd"))] +#[allow(missing_docs)] pub mod ptrace; #[cfg(target_os = "linux")] pub mod quota; #[cfg(any(target_os = "linux"))] +#[allow(missing_docs)] pub mod reboot; #[cfg(not(any(target_os = "redox", target_os = "fuchsia", target_os = "illumos")))] +#[allow(missing_docs)] pub mod resource; #[cfg(not(target_os = "redox"))] +#[allow(missing_docs)] pub mod select; #[cfg(any(target_os = "android", @@ -70,16 +82,21 @@ pub mod select; target_os = "ios", target_os = "linux", target_os = "macos"))] +#[allow(missing_docs)] pub mod sendfile; +#[allow(missing_docs)] pub mod signal; #[cfg(any(target_os = "android", target_os = "linux"))] +#[allow(missing_docs)] pub mod signalfd; #[cfg(not(target_os = "redox"))] +#[allow(missing_docs)] pub mod socket; +#[allow(missing_docs)] pub mod stat; #[cfg(any(target_os = "android", @@ -90,25 +107,34 @@ pub mod stat; target_os = "macos", target_os = "openbsd" ))] +#[allow(missing_docs)] pub mod statfs; pub mod statvfs; #[cfg(any(target_os = "android", target_os = "linux"))] +#[allow(missing_docs)] pub mod sysinfo; +#[allow(missing_docs)] pub mod termios; +#[allow(missing_docs)] pub mod time; +#[allow(missing_docs)] pub mod uio; +#[allow(missing_docs)] pub mod utsname; +#[allow(missing_docs)] pub mod wait; #[cfg(any(target_os = "android", target_os = "linux"))] +#[allow(missing_docs)] pub mod inotify; #[cfg(target_os = "linux")] +#[allow(missing_docs)] pub mod timerfd; diff --git a/src/sys/signal.rs b/src/sys/signal.rs index 95663687..89bcc1a2 100644 --- a/src/sys/signal.rs +++ b/src/sys/signal.rs @@ -1,7 +1,7 @@ // Portions of this file are Copyright 2014 The Rust Project Developers. // See https://www.rust-lang.org/policies/licenses. -///! Operating system signals. +//! Operating system signals. use crate::{Error, Result}; use crate::errno::Errno; |