feat(sigsafe): add filesystem wrappers

Co-authored-by: GPT-5 Codex <codex@openai.com>

Author: wan9chi

Cargo.lock

@@ -8,7 +8,10 @@ publish = false
 doctest = false
 
 [target.'cfg(unix)'.dependencies]
-rustix = { workspace = true }
+rustix = { workspace = true, features = ["fs"] }
+
+[target.'cfg(target_os = "macos")'.dependencies]
+libc = { workspace = true }
 
 # On Linux the page size is probed from the kernel directly (see param.rs);
 # rustix's `param` is only needed where sysconf is the platform interface.
@@ -19,6 +22,7 @@ rustix = { workspace = true, features = ["param"] }
 # item to reference; `runtime` is the module that has one.
 [target.'cfg(target_os = "linux")'.dependencies]
 rustix = { workspace = true, features = ["runtime"] }
+syscalls = { workspace = true }
 
 # Cross-validates the page-size probe against rustix's auxv-based answer.
 [target.'cfg(target_os = "linux")'.dev-dependencies]

crates/sigsafe/Cargo.toml

@@ -29,6 +29,7 @@ rustix can be built with a libc backend instead of raw syscalls, and anything in
 Functions whose rustix implementation already meets the rules are re-exposed as-is; being listed in a module here is what marks a call as allowed, and the backend check above is what keeps that true.
 
 - `mm` — anonymous memory mappings: `mmap_anonymous`, `munmap`.
+- `fs` — caller-buffer filesystem operations: `getcwd`, plus macOS `fcntl_getpath`.
 - `param` — `page_size`.
 
 Allocation without malloc lives in [`sigsafe_alloc`](../sigsafe_alloc).

crates/sigsafe/README.md

@@ -0,0 +1,232 @@
+use core::{
+    cmp::Ordering,
+    ffi::c_char,
+    fmt,
+    hash::{Hash, Hasher},
+    marker::PhantomData,
+    num::NonZeroUsize,
+    ptr::NonNull,
+    slice,
+};
+
+/// Marks a [`CStr`] whose length is not known.
+#[derive(Clone, Copy)]
+pub struct Thin {
+    _private: (),
+}
+
+/// Marks a [`CStr`] that retains its length, including the terminating NUL.
+#[derive(Clone, Copy)]
+pub struct Fat {
+    len_with_nul: NonZeroUsize,
+}
+
+/// A borrowed NUL-terminated string.
+///
+/// The representation parameter records whether the string's length is
+/// available without scanning:
+///
+/// - [`CStr<'_, Thin>`] stores only the string pointer.
+/// - [`CStr<'_, Fat>`] also stores the length including the terminating NUL.
+///
+/// This is a Rust representation, not an FFI type. Pass [`CStr::as_ptr`] to C
+/// functions rather than placing `CStr` in an `extern` function signature.
+#[derive(Clone, Copy)]
+pub struct CStr<'a, R> {
+    ptr: NonNull<c_char>,
+    repr: R,
+    lifetime: PhantomData<&'a c_char>,
+}
+
+impl<R> CStr<'_, R> {
+    /// Returns a pointer to the first byte of this C string.
+    #[must_use]
+    pub const fn as_ptr(&self) -> *const c_char {
+        self.ptr.as_ptr()
+    }
+
+    #[doc(hidden)]
+    #[must_use]
+    pub fn into_repr(self) -> R {
+        self.repr
+    }
+}
+
+impl Fat {
+    /// Returns the represented number of bytes, including the terminating NUL.
+    #[doc(hidden)]
+    #[must_use]
+    pub const fn len_with_nul(self) -> usize {
+        self.len_with_nul.get()
+    }
+}
+
+impl<'a> CStr<'a, Thin> {
+    /// Creates a thin C string view without finding its length.
+    ///
+    /// # Safety
+    ///
+    /// `ptr` must be non-null and point to an immutable NUL-terminated string
+    /// that remains valid for the lifetime of the returned view.
+    #[must_use]
+    pub const unsafe fn from_ptr(ptr: *const c_char) -> Self {
+        Self {
+            // SAFETY: upheld by the caller.
+            ptr: unsafe { NonNull::new_unchecked(ptr.cast_mut()) },
+            repr: Thin { _private: () },
+            lifetime: PhantomData,
+        }
+    }
+
+    /// Counts the bytes before the terminating NUL and returns a
+    /// length-retaining view.
+    #[must_use]
+    pub fn count(self) -> CStr<'a, Fat> {
+        let mut count = 0;
+        // Volatile reads prevent this loop from being replaced with a libc
+        // `strlen` call, which is forbidden by `sigsafe` on Linux.
+        // SAFETY: `CStr<Thin>` points to a NUL-terminated string.
+        while unsafe { self.as_ptr().add(count).read_volatile() } != 0 {
+            count += 1;
+        }
+        let len_with_nul = count + 1;
+
+        CStr {
+            ptr: self.ptr,
+            repr: Fat {
+                // SAFETY: every C string contains at least its terminating
+                // NUL.
+                len_with_nul: unsafe { NonZeroUsize::new_unchecked(len_with_nul) },
+            },
+            lifetime: PhantomData,
+        }
+    }
+}
+
+impl<'a> CStr<'a, Fat> {
+    /// Creates a length-retaining C string from a byte slice without
+    /// validation.
+    ///
+    /// # Safety
+    ///
+    /// `bytes` must end with exactly one NUL byte and contain no other NUL
+    /// bytes.
+    #[must_use]
+    pub const unsafe fn from_bytes_with_nul_unchecked(bytes: &'a [u8]) -> Self {
+        Self {
+            // SAFETY: a valid C string is nonempty, so its pointer is non-null.
+            ptr: unsafe { NonNull::new_unchecked(bytes.as_ptr().cast::<c_char>().cast_mut()) },
+            repr: Fat {
+                // SAFETY: a valid C string contains at least its terminating
+                // NUL.
+                len_with_nul: unsafe { NonZeroUsize::new_unchecked(bytes.len()) },
+            },
+            lifetime: PhantomData,
+        }
+    }
+
+    /// Returns this string as a thin C string without scanning it.
+    #[must_use]
+    pub const fn into_thin(self) -> CStr<'a, Thin> {
+        CStr { ptr: self.ptr, repr: Thin { _private: () }, lifetime: PhantomData }
+    }
+
+    /// Returns the string's bytes without the terminating NUL.
+    #[must_use]
+    pub const fn as_bytes(&self) -> &'a [u8] {
+        // SAFETY: this view carries the exact initialized C string length.
+        unsafe { slice::from_raw_parts(self.ptr.as_ptr().cast(), self.count_bytes()) }
+    }
+
+    /// Returns the string's bytes, including the terminating NUL.
+    #[must_use]
+    pub const fn as_bytes_with_nul(&self) -> &'a [u8] {
+        // SAFETY: this view carries the exact initialized C string length.
+        unsafe { slice::from_raw_parts(self.ptr.as_ptr().cast(), self.len_with_nul()) }
+    }
+
+    /// Returns the number of bytes including the terminating NUL.
+    #[must_use]
+    pub const fn len_with_nul(&self) -> usize {
+        self.repr.len_with_nul()
+    }
+
+    /// Returns the number of bytes before the terminating NUL.
+    #[must_use]
+    pub const fn count_bytes(&self) -> usize {
+        self.len_with_nul() - 1
+    }
+
+    /// Returns whether this C string is empty.
+    #[must_use]
+    pub const fn is_empty(&self) -> bool {
+        self.count_bytes() == 0
+    }
+
+    pub(crate) const fn as_core_c_str(&self) -> &core::ffi::CStr {
+        // SAFETY: `CStr<Fat>` maintains the same byte invariant.
+        unsafe { core::ffi::CStr::from_bytes_with_nul_unchecked(self.as_bytes_with_nul()) }
+    }
+}
+
+impl fmt::Debug for CStr<'_, Thin> {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.debug_tuple("CStr").field(&self.as_ptr()).finish()
+    }
+}
+
+impl fmt::Debug for CStr<'_, Fat> {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.as_core_c_str().fmt(formatter)
+    }
+}
+
+impl PartialEq for CStr<'_, Fat> {
+    fn eq(&self, other: &Self) -> bool {
+        self.as_bytes() == other.as_bytes()
+    }
+}
+
+impl Eq for CStr<'_, Fat> {}
+
+impl PartialOrd for CStr<'_, Fat> {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for CStr<'_, Fat> {
+    fn cmp(&self, other: &Self) -> Ordering {
+        self.as_bytes().cmp(other.as_bytes())
+    }
+}
+
+impl Hash for CStr<'_, Fat> {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        self.as_bytes().hash(state);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use core::mem::size_of;
+
+    use super::{CStr, Fat, Thin};
+
+    #[test]
+    fn representations_retain_the_expected_metadata() {
+        // SAFETY: the byte string contains one trailing NUL.
+        let fat = unsafe { CStr::<Fat>::from_bytes_with_nul_unchecked(b"abc\0") };
+        let thin = fat.into_thin();
+        let counted = thin.count();
+
+        assert_eq!(size_of::<CStr<'_, Thin>>(), size_of::<*const u8>());
+        assert_eq!(size_of::<CStr<'_, Fat>>(), size_of::<(*const u8, usize)>());
+        assert_eq!(thin.as_ptr(), fat.as_ptr());
+        assert_eq!(fat.len_with_nul(), 4);
+        assert_eq!(fat.count_bytes(), 3);
+        assert_eq!(fat.as_bytes(), b"abc");
+        assert_eq!(fat.as_bytes_with_nul(), b"abc\0");
+        assert_eq!(counted, fat);
+    }
+}

crates/sigsafe/src/c_str.rs

@@ -0,0 +1,52 @@
+use core::{mem::MaybeUninit, slice};
+
+use rustix::{
+    fd::{FromRawFd as _, OwnedFd},
+    fs::{Mode, OFlags},
+};
+
+use crate::{CStr, Errno, Fat, Result};
+
+// Linux UAPI `PATH_MAX`.
+pub(super) const PATH_MAX: usize = 4096;
+const AT_FDCWD: usize = (-100_isize).cast_unsigned();
+
+#[expect(clippy::needless_pass_by_value, reason = "CStr is a borrowed value type")]
+pub(super) fn open<R>(path: CStr<'_, R>, flags: OFlags, mode: Mode) -> Result<OwnedFd> {
+    // SAFETY: `path` points to a NUL-terminated string for the duration of the
+    // call, and the remaining arguments are passed through unchanged.
+    let fd = unsafe {
+        syscalls::syscall4(
+            syscalls::Sysno::openat,
+            AT_FDCWD,
+            path.as_ptr().addr(),
+            flags.bits() as usize,
+            mode.bits() as usize,
+        )
+    }
+    .map_err(|errno| Errno::from_raw_os_error(errno.into_raw()))?;
+
+    // SAFETY: a successful `openat` syscall returns a nonnegative raw file
+    // descriptor represented by `c_int`.
+    let fd = unsafe { i32::try_from(fd).unwrap_unchecked() };
+    // SAFETY: ownership of the newly opened descriptor transfers to `OwnedFd`.
+    Ok(unsafe { OwnedFd::from_raw_fd(fd) })
+}
+
+pub(super) fn getcwd(buf: &mut [MaybeUninit<u8>]) -> Result<CStr<'_, Fat>> {
+    // rustix has this allocation-free backend operation internally, but
+    // exposes only an allocating `getcwd` that owns and may grow a `Vec`.
+    // Issue the same raw syscall here until rustix exposes its
+    // caller-buffer operation publicly.
+    // SAFETY: `buf` is writable for exactly `buf.len()` bytes. The Linux
+    // `getcwd` syscall writes no more than that and returns the number of
+    // initialized bytes, including its terminating NUL.
+    let initialized =
+        unsafe { syscalls::syscall2(syscalls::Sysno::getcwd, buf.as_mut_ptr().addr(), buf.len()) }
+            .map_err(|errno| Errno::from_raw_os_error(errno.into_raw()))?;
+
+    // SAFETY: the syscall initialized this prefix through its terminating NUL.
+    let bytes = unsafe { slice::from_raw_parts(buf.as_ptr().cast(), initialized) };
+    // SAFETY: the syscall returned one NUL-terminated pathname.
+    Ok(unsafe { CStr::from_bytes_with_nul_unchecked(bytes) })
+}