commit 3aaf25aaec21a4157b812ab63a9a1f16e5d0a850
parent c5d98e320524ed7a448354c549f7b98d70dc7518
Author: Zack Newman <zack@philomathiclife.com>
Date: Tue, 6 Jan 2026 17:41:34 -0700
improve docs
Diffstat:
5 files changed, 50 insertions(+), 69 deletions(-)
diff --git a/Cargo.toml b/Cargo.toml
@@ -91,7 +91,8 @@ semicolon_inside_block = "allow"
[package.metadata.docs.rs]
all-features = true
-default-target = "x86_64-unknown-linux-gnu"
+cargo-args = ["-Zbuild-std=std"]
+default-target = "x86_64-unknown-openbsd"
targets = [
"aarch64-apple-darwin",
"aarch64-unknown-linux-gnu",
@@ -100,12 +101,13 @@ targets = [
"powerpc64-unknown-linux-gnu",
"riscv64gc-unknown-linux-gnu",
"x86_64-unknown-freebsd",
+ "x86_64-unknown-linux-gnu",
"x86_64-unknown-linux-musl",
"x86_64-unknown-netbsd"
]
[dev-dependencies]
-tokio = { version = "1.48.0", default-features = false, features = ["macros", "net", "rt"] }
+tokio = { version = "1.49.0", default-features = false, features = ["macros", "net", "rt"] }
### FEATURES #################################################################
diff --git a/README.md b/README.md
@@ -5,10 +5,8 @@ Privilege separation library for Unix-likes OSes
[<img alt="crates.io" src="https://img.shields.io/crates/v/priv_sep.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/priv_sep)
[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-priv_sep-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/priv_sep/latest/priv_sep/)
-`priv_sep` is a library that uses the system's libc to perform privilege separation and privilege reduction.
-
-Note the only platforms that are currently supported are platforms that correspond to the following
-`target_os` values:
+`priv_sep` is a library that uses the system's libc to perform privilege separation and privilege reduction
+for Unix-like platforms. The following `target_os` values are supported:
* `dragonfly`
* `freebsd`
@@ -50,7 +48,8 @@ async fn main() -> Result<Infallible, PrivDropErr<Error>> {
}
```
-## `priv_sep` in action for OpenBSD incorporating `pledge(2)` and `unveil(2)`
+<details>
+<summary>Incorporating <a href="https://man.openbsd.org/pledge.2"><code>pledge(2)</code></a> and <a href="https://man.openbsd.org/unveil.2"><code>unveil(2)</code></a> on OpenBSD</summary>
```rust
use core::{convert::Infallible, ffi::CStr};
@@ -106,6 +105,7 @@ async fn main() -> Result<Infallible, PrivDropErr<Error>> {
}
}
```
+</details>
## Minimum Supported Rust Version (MSRV)
@@ -142,8 +142,8 @@ in the `priv_sep` directory.
Additionally, one should test all `ignore` tests as both root and non-root for both toolchains. These tests should
be run individually since they may interfere with each other.
-Last, `RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features` should be run to ensure documentation can be
-built on non-OpenBSD platforms; otherwise `cargo doc --all-features` should be run.
+Last, `RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features -Zbuild-std=std` should be run to ensure
+documentation can be built.
### Status
diff --git a/src/err.rs b/src/err.rs
@@ -555,7 +555,7 @@ pub enum Errno {
docsrs,
doc(cfg(any(target_arch = "powerpc", target_arch = "powerpc64")))
)]
- #[cfg(any(doc, target_arch = "powerpc", target_arch = "powerpc64"))]
+ #[cfg(any(target_arch = "powerpc", target_arch = "powerpc64"))]
EDEADLOCK,
/// Bad font file format.
EBFONT = 59,
@@ -1922,12 +1922,14 @@ impl Errno {
pub const EAGAIN: Self = Self::EWOULDBLOCK;
/// Operation not supported.
#[cfg_attr(docsrs, doc(cfg(any(target_os = "dragonfly", target_os = "freebsd"))))]
- #[cfg(any(doc, target_os = "dragonfly", target_os = "freebsd"))]
+ #[cfg(any(target_os = "dragonfly", target_os = "freebsd"))]
pub const ENOTSUP: Self = Self::EOPNOTSUPP;
/// Must be equal to largest `Errno`.
+ #[cfg_attr(docsrs, doc(cfg(target_os = "dragonfly")))]
#[cfg(target_os = "dragonfly")]
pub const LAST: Self = Self::EASYNC;
/// Must be equal to largest `Errno`.
+ #[cfg_attr(docsrs, doc(cfg(target_os = "freebsd")))]
#[cfg(target_os = "freebsd")]
pub const LAST: Self = Self::EINTEGRITY;
/// Resource deadlock would occur.
@@ -1947,30 +1949,30 @@ impl Errno {
target_os = "linux"
)))
)]
- #[cfg(any(
- doc,
- all(
- not(any(
- target_arch = "mips",
- target_arch = "mips32r6",
- target_arch = "mips64",
- target_arch = "mips64r6",
- target_arch = "powerpc",
- target_arch = "powerpc64",
- target_arch = "sparc",
- target_arch = "sparc64",
- )),
- target_os = "linux"
- )
+ #[cfg(all(
+ not(any(
+ target_arch = "mips",
+ target_arch = "mips32r6",
+ target_arch = "mips64",
+ target_arch = "mips64r6",
+ target_arch = "powerpc",
+ target_arch = "powerpc64",
+ target_arch = "sparc",
+ target_arch = "sparc64",
+ )),
+ target_os = "linux"
))]
pub const EDEADLOCK: Self = Self::EDEADLK;
/// Must be equal to largest `Errno`.
+ #[cfg_attr(docsrs, doc(cfg(target_os = "macos")))]
#[cfg(target_os = "macos")]
pub const LAST: Self = Self::ENOTCAPABLE;
/// Must be equal to largest `Errno`.
+ #[cfg_attr(docsrs, doc(cfg(target_os = "netbsd")))]
#[cfg(target_os = "netbsd")]
pub const LAST: Self = Self::ENOTRECOVERABLE;
/// Must be equal to largest `Errno`.
+ #[cfg_attr(docsrs, doc(cfg(target_os = "openbsd")))]
#[cfg(target_os = "openbsd")]
pub const LAST: Self = Self::EPROTO;
/// Returns a `Self` equivalent to `code`.
diff --git a/src/lib.rs b/src/lib.rs
@@ -5,7 +5,14 @@
//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
//!
//! `priv_sep` is a library that uses the system's libc to perform privilege separation and privilege reduction
-//! for Unix-like platforms.
+//! for Unix-like platforms. The following `target_os` values are supported:
+//!
+//! * `dragonfly`
+//! * `freebsd`
+//! * `linux`
+//! * `macos`
+//! * `netbsd`
+//! * `openbsd`
//!
//! ## `priv_sep` in action
//!
@@ -40,18 +47,21 @@
//! }
//! ```
//!
-//! ## `priv_sep` in action for OpenBSD incorporating `pledge(2)` and `unveil(2)`
+//! <details>
+//! <summary>Incorporating <a href="https://man.openbsd.org/pledge.2"><code>pledge(2)</code></a> and <a href="https://man.openbsd.org/unveil.2"><code>unveil(2)</code></a> on OpenBSD</summary>
//!
//! ```no_run
//! # #[cfg(target_os = "openbsd")]
//! use core::{convert::Infallible, ffi::CStr};
//! # #[cfg(target_os = "openbsd")]
//! use priv_sep::{Permissions, PrivDropErr, Promise, Promises};
+//! # #[cfg(target_os = "openbsd")]
//! use std::{
//! fs,
//! io::Error,
//! net::{Ipv6Addr, SocketAddrV6},
//! };
+//! # #[cfg(target_os = "openbsd")]
//! use tokio::net::TcpListener;
//! # #[cfg(not(target_os = "openbsd"))]
//! # fn main() {}
@@ -101,7 +111,9 @@
//! }
//! }
//! ```
+//! </details>
#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, doc(auto_cfg = false))]
#![no_std]
#![cfg(any(
target_os = "dragonfly",
@@ -122,7 +134,7 @@ mod c;
/// Errno.
mod err;
/// OpenBSD
-#[cfg(any(doc, target_os = "openbsd"))]
+#[cfg(target_os = "openbsd")]
mod openbsd;
use c::SUCCESS;
use core::{
@@ -134,7 +146,7 @@ use core::{
};
pub use err::Errno;
#[cfg_attr(docsrs, doc(cfg(target_os = "openbsd")))]
-#[cfg(any(doc, target_os = "openbsd"))]
+#[cfg(target_os = "openbsd")]
pub use openbsd::{Permission, Permissions, Promise, Promises};
/// [`uid_t`](https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/basedefs/sys_types.h.html).
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -909,27 +921,10 @@ impl PartialEq<UserInfo> for &UserInfo {
/// # Examples
///
/// ```no_run
-/// # #[cfg(any(target_os = "dragonfly", target_os = "freebsd", target_os = "linux", target_os = "netbsd", target_os = "openbsd"))]
/// assert!(priv_sep::setgroups(&[]).is_ok());
/// ```
-#[cfg_attr(
- docsrs,
- doc(cfg(any(
- target_os = "dragonfly",
- target_os = "freebsd",
- target_os = "linux",
- target_os = "netbsd",
- target_os = "openbsd"
- )))
-)]
-#[cfg(any(
- target_os = "dragonfly",
- target_os = "freebsd",
- target_os = "linux",
- target_os = "netbsd",
- target_os = "openbsd",
- all(doc, target_os = "macos")
-))]
+#[cfg_attr(docsrs, doc(cfg(not(target_os = "macos"))))]
+#[cfg(not(target_os = "macos"))]
#[expect(unsafe_code, reason = "setgroups(2) takes a pointer")]
#[inline]
pub fn setgroups(groups: &[Gid]) -> Result<(), Errno> {
@@ -966,27 +961,10 @@ pub fn setgroups(groups: &[Gid]) -> Result<(), Errno> {
/// # Examples
///
/// ```no_run
-/// # #[cfg(any(target_os = "dragonfly", target_os = "freebsd", target_os = "linux", target_os = "netbsd", target_os = "openbsd"))]
/// assert!(priv_sep::drop_supplementary_groups().is_ok());
/// ```
-#[cfg_attr(
- docsrs,
- doc(cfg(any(
- target_os = "dragonfly",
- target_os = "freebsd",
- target_os = "linux",
- target_os = "netbsd",
- target_os = "openbsd"
- )))
-)]
-#[cfg(any(
- target_os = "dragonfly",
- target_os = "freebsd",
- target_os = "linux",
- target_os = "netbsd",
- target_os = "openbsd",
- all(doc, target_os = "macos")
-))]
+#[cfg_attr(docsrs, doc(cfg(not(target_os = "macos"))))]
+#[cfg(not(target_os = "macos"))]
#[expect(unsafe_code, reason = "setgroups(2) takes a pointer")]
#[inline]
pub fn drop_supplementary_groups() -> Result<(), Errno> {
diff --git a/src/openbsd.rs b/src/openbsd.rs
@@ -1,4 +1,3 @@
-#![cfg_attr(docsrs, doc(cfg(target_os = "openbsd")))]
#[cfg(doc)]
use super::chroot_then_chdir;
use super::{Errno, PrivDropErr, SUCCESS, UserInfo};
