feat(syscalls): thin wrappers around raw syscalls

system/linux/syscalls/WRAP_PROGRESS.md

@@ -0,0 +1,239 @@
+# Wrap Progress
+
+This checklist tracks the next layer above the raw Linux syscall wrappers.
+The goal of this layer is to preserve the raw syscall shape while removing
+the most mechanical Rust rough edges.
+
+## Scope
+
+The wrap layer should:
+
+- convert raw syscall return values into `Result<T, E>`;
+- use syscall-specific error enums, with an `Other(Errno)` escape hatch when
+  the syscall can delegate to file systems, drivers, protocols, security
+  modules, or other helpers with wider reachable errors;
+- use shared slices for `*const T` plus length arguments;
+- use mutable slices for `*mut T` plus length arguments when the kernel reads
+  and writes initialized elements;
+- use `MaybeUninit` for output buffers or output slots that the kernel
+  initializes;
+- use shared references for non-null single-item `*const T` arguments;
+- use mutable references for non-null single-item `*mut T` arguments when the
+  pointed-to value must already be initialized;
+- use `Option<&T>`, `Option<&mut T>`, or `Option<&mut MaybeUninit<T>>` when
+  null is a meaningful syscall input;
+- use `&CStr` for NUL-terminated `*const Char` strings;
+- stay safe whenever the wrapper removes all caller-visible memory-safety
+  preconditions;
+- use strict-provenance APIs when converting pointers before passing raw
+  integer syscall arguments.
+
+The wrap layer should not introduce ownership, buffering, retry policy, path
+encoding policy, automatic descriptor closing, or broad semantic convenience.
+Those belong in higher layers.
+
+## Module Layout
+
+The existing `sys` module remains the raw syscall layer. Its wrappers keep the
+exact kernel-facing ABI shape: raw pointer arguments, raw integer return values,
+and `unsafe` where the caller must uphold memory-safety preconditions.
+
+The crate root exports the wrap layer. `lib.rs` should mirror the shape of
+`sys.rs`: declare per-syscall wrapper modules and re-export each public wrapper
+and its syscall-specific error type from the crate root. For example,
+`celer_system_linux_syscalls::read` is the wrapped API, while
+`celer_system_linux_syscalls::sys::read` is the raw API.
+
+Architecture availability should mirror the raw layer. Top-level wrapped
+modules and re-exports must use the same kind of `cfg` gates as the raw
+syscalls so only syscalls available on the current target are exposed.
+
+Historical Linux 1.0 ABI wrappers should be exposed from a top-level
+`linux_1_0` module, mirroring `sys::linux_1_0`.
+
+## Errno
+
+The shared errno representation should be an enum. Common errno values should
+be listed explicitly, and a raw variant should carry any errno value that the
+crate does not list explicitly.
+
+The raw variant should hold a `u16` value. When a raw syscall return is in the
+kernel errno range `-4095..=-1`, the stored errno value is the negated kernel
+return value.
+
+Syscall-specific error enums should use explicit variants for source-verified
+reachable errors. They should include an `Other(Errno)` variant when the syscall
+can return delegated, object-specific, or otherwise open-ended errors.
+
+## Done Criteria
+
+A checked syscall means:
+
+- the wrapper exists and is public from the wrap layer;
+- each pointer argument has been classified as input, output, in/out, nullable,
+  or NUL-terminated string from kernel source;
+- each safe/unsafe choice follows the repository unsafe rule;
+- the success return type is semantic for this syscall;
+- reachable direct errors are represented in a syscall-specific error type;
+- delegated or object-specific errors use `Other(Errno)` unless the reachable
+  set is source-verified to be closed;
+- tests cover success and at least one practical error path when feasible.
+
+## Documentation
+
+Wrapped syscall docs should document wrapper semantics, not kernel behavior.
+Kernel support, historical notes, required privileges, detailed behavior,
+reachable error analysis, and source references belong in `sys::*`.
+
+Each wrapped syscall should document:
+
+- the Rust argument conversions it provides;
+- the `Ok(...)` value when it is not obvious;
+- the syscall-specific error variants;
+- any remaining caller-visible safety precondition;
+- a link to the raw `sys::*` wrapper for kernel behavior, reachable errors,
+  and source references.
+
+## Helpers
+
+Shared conversion helpers should live in a private `helpers` module.
+
+## Checklist
+
+- [x] `access` - x86, x86_64
+- [x] `acct`
+- [x] `adjtimex`
+- [x] `alarm` - x86, x86_64
+- [x] `brk`
+- [x] `chdir`
+- [x] `chmod` - x86, x86_64
+- [x] `chroot`
+- [x] `close`
+- [x] `creat` - x86, x86_64
+- [x] `create_module` - x86
+- [x] `delete_module`
+- [x] `dup`
+- [x] `dup2` - x86, x86_64
+- [x] `execve`
+- [x] `exit`
+- [x] `fchdir`
+- [x] `fchmod`
+- [x] `fchown16` - x86
+- [x] `fcntl`
+- [x] `fork` - x86
+- [x] `fstatfs`
+- [x] `fsync`
+- [x] `ftruncate`
+- [x] `get_kernel_syms` - x86
+- [x] `getegid16` - x86
+- [x] `geteuid16` - x86
+- [x] `getgid16` - x86
+- [x] `getgroups16` - x86
+- [x] `getitimer`
+- [x] `getpgid`
+- [x] `getpgrp` - x86, x86_64
+- [x] `getpid`
+- [x] `getppid`
+- [x] `getpriority`
+- [x] `getrlimit`
+- [x] `getrusage`
+- [x] `gettimeofday`
+- [x] `getuid16` - x86
+- [x] `idle` - x86
+- [x] `init_module`
+- [x] `ioctl`
+- [x] `ioperm` - x86
+- [x] `iopl` - x86
+- [x] `ipc` - x86
+- [x] `kill`
+- [x] `lchown16` - x86
+- [x] `link` - x86, x86_64
+- [x] `lseek`
+- [x] `mknod` - x86, x86_64
+- [x] `mkdir` - x86, x86_64
+- [x] `mmap`
+- [x] `modify_ldt` - x86
+- [x] `mount`
+- [x] `munmap`
+- [x] `newfstat`
+- [x] `newlstat` - x86, x86_64
+- [x] `newuname`
+- [x] `nice` - x86
+- [x] `oldfstat` - x86
+- [x] `oldlstat` - x86
+- [x] `oldolduname` - x86
+- [x] `oldstat` - x86
+- [x] `olduname` - x86
+- [x] `open` - x86, x86_64
+- [x] `pause` - x86, x86_64
+- [x] `pipe` - x86, x86_64
+- [x] `ptrace`
+- [x] `read`
+- [x] `readdir` - x86
+- [x] `readlink` - x86, x86_64
+- [x] `reboot`
+- [x] `rename` - x86, x86_64
+- [x] `rmdir` - x86, x86_64
+- [x] `select` - x86, x86_64
+- [x] `setdomainname`
+- [x] `setgid16` - x86
+- [x] `setgroups16` - x86
+- [x] `sethostname`
+- [x] `setitimer`
+- [x] `setpgid`
+- [x] `setpriority`
+- [x] `setregid16` - x86
+- [x] `setreuid16` - x86
+- [x] `setrlimit`
+- [x] `setsid`
+- [x] `settimeofday`
+- [x] `setuid16` - x86
+- [x] `sgetmask` - x86
+- [x] `sigaction` - x86
+- [x] `signal` - x86
+- [x] `sigpending` - x86
+- [x] `sigprocmask` - x86
+- [x] `sigreturn` - x86
+- [x] `sigsuspend` - x86
+- [x] `socketcall` - x86
+- [x] `ssetmask` - x86
+- [x] `stat` - x86, x86_64
+- [x] `statfs`
+- [x] `stime` - x86
+- [x] `swapoff`
+- [x] `swapon`
+- [x] `symlink` - x86, x86_64
+- [x] `sync`
+- [x] `sysinfo`
+- [x] `syslog`
+- [x] `time` - x86, x86_64
+- [x] `times`
+- [x] `truncate`
+- [x] `umask`
+- [x] `umount`
+- [x] `unlink` - x86, x86_64
+- [x] `uselib` - x86
+- [x] `ustat` - x86, x86_64
+- [x] `utime` - x86, x86_64
+- [x] `vhangup`
+- [x] `vm86` - x86
+- [x] `wait4`
+- [x] `waitpid` - x86
+- [x] `write`
+
+## Linux 1.0 Historical Variants
+
+These raw wrappers are currently exposed under `sys::linux_1_0` on x86. Decide
+whether the wrap layer mirrors them before checking them off.
+
+- [x] `linux_1_0::fstatfs`
+- [x] `linux_1_0::ftruncate`
+- [x] `linux_1_0::init_module`
+- [x] `linux_1_0::newfstat`
+- [x] `linux_1_0::newlstat`
+- [x] `linux_1_0::setrlimit`
+- [x] `linux_1_0::setup`
+- [x] `linux_1_0::stat`
+- [x] `linux_1_0::statfs`
+- [x] `linux_1_0::sysinfo`
+- [x] `linux_1_0::truncate`

system/linux/syscalls/src/access.rs

@@ -0,0 +1,102 @@
+use core::ffi::CStr;
+
+use celer_system_linux_ctypes::Int;
+
+use crate::errno::Errno;
+use crate::helpers::unit_from_ret;
+use crate::sys;
+
+/// Errors returned by [`access`].
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum AccessError {
+    /// `EINVAL`.
+    Einval,
+    /// `ENOMEM`.
+    Enomem,
+    /// Another errno returned by delegated pathname, permission, or filesystem
+    /// work.
+    Other(Errno),
+}
+
+impl AccessError {
+    fn from_errno(errno: Errno) -> Self {
+        match errno {
+            Errno::Einval => Self::Einval,
+            Errno::Enomem => Self::Enomem,
+            errno => Self::Other(errno),
+        }
+    }
+}
+
+/// Check whether the calling process can access a file by pathname.
+///
+/// This safe wrapper takes a NUL-terminated [`CStr`] pathname and maps the raw
+/// syscall return value into `Result<(), AccessError>`.
+///
+/// On success, returns `Ok(())` when the requested access is permitted.
+///
+/// See [`sys::access`] for kernel behavior, reachable errors, and source
+/// references.
+///
+/// # Errors
+/// - [`AccessError::Einval`]: `mode` contains unsupported bits.
+/// - [`AccessError::Enomem`]: temporary credential allocation failed.
+/// - [`AccessError::Other`]: delegated pathname, permission, or filesystem
+///   error.
+pub fn access(pathname: &CStr, mode: Int) -> Result<(), AccessError> {
+    // SAFETY: the `CStr` argument guarantees a valid, NUL-terminated
+    // pathname pointer for the duration of the call.
+    let ret = unsafe { sys::access(pathname.as_ptr(), mode) };
+
+    unit_from_ret(ret as isize, AccessError::from_errno)
+}
+
+#[cfg(test)]
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod tests {
+    use std::ffi::CString;
+    use std::fs::{self, File};
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    use crate::Errno;
+
+    use super::{AccessError, access};
+
+    fn temp_path() -> std::path::PathBuf {
+        let mut path = std::env::temp_dir();
+        let now = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        path.push(format!("celer_wrap_access_{now}"));
+        path
+    }
+
+    #[test]
+    fn test_access_ok() {
+        let path = temp_path();
+        File::create(&path).unwrap();
+        let path_c = CString::new(path.as_os_str().as_encoded_bytes()).unwrap();
+
+        assert_eq!(access(path_c.as_c_str(), 0), Ok(()));
+
+        fs::remove_file(&path).unwrap();
+    }
+
+    #[test]
+    fn test_access_einval() {
+        let path = CString::new("/tmp").unwrap();
+
+        assert_eq!(access(path.as_c_str(), 0x8000), Err(AccessError::Einval));
+    }
+
+    #[test]
+    fn test_access_error_mapping() {
+        assert_eq!(AccessError::from_errno(Errno::Einval), AccessError::Einval);
+        assert_eq!(AccessError::from_errno(Errno::Enomem), AccessError::Enomem);
+        assert_eq!(
+            AccessError::from_errno(Errno::Enoent),
+            AccessError::Other(Errno::Enoent)
+        );
+    }
+}