From 2d2aa5592b48bab210fa702a3e88e752851015c0 Mon Sep 17 00:00:00 2001 From: Peter Limkilde Svendsen Date: Mon, 6 Apr 2026 20:12:04 +0200 Subject: [PATCH] Document Pal methods --- src/platform/linux/mod.rs | 2 +- src/platform/pal/mod.rs | 109 ++++++++++++++++++++++++++++++++++++++ src/platform/redox/mod.rs | 2 +- 3 files changed, 111 insertions(+), 2 deletions(-) diff --git a/src/platform/linux/mod.rs b/src/platform/linux/mod.rs index 30a8ab790f..c30a163709 100644 --- a/src/platform/linux/mod.rs +++ b/src/platform/linux/mod.rs @@ -67,7 +67,7 @@ pub fn e_raw(sys: usize) -> Result { } } -/// Linux syscall implementation of the platform abstraction layer. +/// Linux syscall implementation of [`Pal`]. pub struct Sys; impl Sys { diff --git a/src/platform/pal/mod.rs b/src/platform/pal/mod.rs index ff5ff9739b..5a99d2dbaf 100644 --- a/src/platform/pal/mod.rs +++ b/src/platform/pal/mod.rs @@ -34,77 +34,111 @@ mod socket; /// Platform abstraction layer, a platform-agnostic abstraction over syscalls. pub trait Pal { + /// Platform implementation of [`access()`](crate::header::unistd::access) from [`unistd.h`](crate::header::unistd). fn access(path: CStr, mode: c_int) -> Result<()>; + /// Platform implementation of [`brk()`](crate::header::unistd::brk) from [`unistd.h`](crate::header::unistd). unsafe fn brk(addr: *mut c_void) -> Result<*mut c_void>; + /// Platform implementation of [`chdir()`](crate::header::unistd::chdir) from [`unistd.h`](crate::header::unistd). fn chdir(path: CStr) -> Result<()>; + /// Platform implementation of [`chmod()`](crate::header::sys_stat::chmod) from [`sys/stat.h`](crate::header::sys_stat). fn chmod(path: CStr, mode: mode_t) -> Result<()>; + /// Platform implementation of [`chown()`](crate::header::unistd::chown) from [`unistd.h`](crate::header::unistd). fn chown(path: CStr, owner: uid_t, group: gid_t) -> Result<()>; + /// Platform implementation of [`clock_getres()`](crate::header::time::clock_getres) from [`time.h`](crate::header::time). fn clock_getres(clk_id: clockid_t, tp: Option>) -> Result<()>; // TODO: maybe remove tp and change signature to -> Result? + /// Platform implementation of [`clock_gettime()`](crate::header::time::clock_gettime) from [`time.h`](crate::header::time). fn clock_gettime(clk_id: clockid_t, tp: Out) -> Result<()>; + /// Platform implementation of [`clock_settime()`](crate::header::time::clock_settime) from [`time.h`](crate::header::time). unsafe fn clock_settime(clk_id: clockid_t, tp: *const timespec) -> Result<()>; + /// Platform implementation of [`close()`](crate::header::unistd::close) from [`unistd.h`](crate::header::unistd). fn close(fildes: c_int) -> Result<()>; + /// Platform implementation of [`dup()`](crate::header::unistd::dup) from [`unistd.h`](crate::header::unistd). fn dup(fildes: c_int) -> Result; + /// Platform implementation of [`dup2()`](crate::header::unistd::dup2) from [`unistd.h`](crate::header::unistd). fn dup2(fildes: c_int, fildes2: c_int) -> Result; + /// Platform implementation of [`execve()`](crate::header::unistd::execve) from [`unistd.h`](crate::header::unistd). unsafe fn execve(path: CStr, argv: *const *mut c_char, envp: *const *mut c_char) -> Result<()>; + + /// Platform implementation of [`fexecve()`](crate::header::unistd::fexecve) from [`unistd.h`](crate::header::unistd). unsafe fn fexecve( fildes: c_int, argv: *const *mut c_char, envp: *const *mut c_char, ) -> Result<()>; + /// Platform implementation of [`_Exit()`](crate::header::stdlib::_Exit) from [`stdlib.h`](crate::header::stdlib) (or the equivalent [`_exit()`](crate::header::unistd::_exit) from [`unistd.h`](crate::header::unistd)). fn exit(status: c_int) -> !; unsafe fn exit_thread(stack_base: *mut (), stack_size: usize) -> !; + /// Platform implementation of [`fchdir()`](crate::header::unistd::fchdir) from [`unistd.h`](crate::header::unistd). fn fchdir(fildes: c_int) -> Result<()>; + /// Platform implementation of [`fchmod()`](crate::header::sys_stat::fchmod) from [`sys/stat.h`](crate::header::sys_stat). fn fchmod(fildes: c_int, mode: mode_t) -> Result<()>; + + /// Platform implementation of [`fchmodat()`](crate::header::sys_stat::fchmodat) from [`sys/stat.h`](crate::header::sys_stat). fn fchmodat(dirfd: c_int, path: Option, mode: mode_t, flags: c_int) -> Result<()>; + /// Platform implementation of [`fchown()`](crate::header::unistd::fchown) from [`unistd.h`](crate::header::unistd). fn fchown(fildes: c_int, owner: uid_t, group: gid_t) -> Result<()>; + /// Platform implementation of [`fdatasync()`](crate::header::unistd::fdatasync) from [`unistd.h`](crate::header::unistd). fn fdatasync(fildes: c_int) -> Result<()>; + /// Platform implementation of [`flock()`](crate::header::sys_file::flock) from [`sys/file.h`](crate::header::sys_file). fn flock(fd: c_int, operation: c_int) -> Result<()>; + /// Platform implementation of [`fstat()`](crate::header::sys_stat::fstat) from [`sys/stat.h`](crate::header::sys_stat). fn fstat(fildes: c_int, buf: Out) -> Result<()>; + /// Platform implementation of [`fstatat()`](crate::header::sys_stat::fstatat) from [`sys/stat.h`](crate::header::sys_stat). fn fstatat(fildes: c_int, path: Option, buf: Out, flags: c_int) -> Result<()>; + /// Platform implementation of [`fstatvfs()`](crate::header::sys_statvfs::fstatvfs) from [`sys/statvfs.h`](crate::header::sys_statvfs). fn fstatvfs(fildes: c_int, buf: Out) -> Result<()>; + /// Platform implementation of [`fcntl()`](crate::header::fcntl::fcntl) from [`fcntl.h`](crate::header::fcntl). fn fcntl(fildes: c_int, cmd: c_int, arg: c_ulonglong) -> Result; + /// Platform implementation of [`_Fork()`](crate::header::unistd::_Fork) from [`unistd.h`](crate::header::unistd). unsafe fn fork() -> Result; fn fpath(fildes: c_int, out: &mut [u8]) -> Result; + /// Platform implementation of [`fsync()`](crate::header::unistd::fsync) from [`unistd.h`](crate::header::unistd). fn fsync(fildes: c_int) -> Result<()>; + /// Platform implementation of [`ftruncate()`](crate::header::unistd::ftruncate) from [`unistd.h`](crate::header::unistd). fn ftruncate(fildes: c_int, length: off_t) -> Result<()>; unsafe fn futex_wait(addr: *mut u32, val: u32, deadline: Option<×pec>) -> Result<()>; + unsafe fn futex_wake(addr: *mut u32, num: u32) -> Result; + /// Platform implementation of [`futimens()`](crate::header::sys_stat::futimens) from [`sys/stat.h`](crate::header::sys_stat). unsafe fn futimens(fd: c_int, times: *const timespec) -> Result<()>; + /// Platform implementation of `utimens()` (TODO) from [`sys/stat.h`](crate::header::sys_stat). unsafe fn utimens(path: CStr, times: *const timespec) -> Result<()>; + /// Platform implementation of [`getcwd()`](crate::header::unistd::getcwd) from [`unistd.h`](crate::header::unistd). fn getcwd(buf: Out<[u8]>) -> Result<()>; fn getdents(fd: c_int, buf: &mut [u8], opaque_offset: u64) -> Result; + fn dir_seek(fd: c_int, opaque_offset: u64) -> Result<()>; // SAFETY: This_dent must satisfy platform-specific size and alignment constraints. On Linux, @@ -113,14 +147,18 @@ pub trait Pal { unsafe fn dent_reclen_offset(this_dent: &[u8], offset: usize) -> Option<(u16, u64)>; // Always successful + /// Platform implementation of [`getegid()`](crate::header::unistd::getegid) from [`unistd.h`](crate::header::unistd). fn getegid() -> gid_t; // Always successful + /// Platform implementation of [`geteuid()`](crate::header::unistd::geteuid) from [`unistd.h`](crate::header::unistd). fn geteuid() -> uid_t; // Always successful + /// Platform implementation of [`getgid()`](crate::header::unistd::getgid) from [`unistd.h`](crate::header::unistd). fn getgid() -> gid_t; + /// Platform implementation of [`getgroups()`](crate::header::unistd::getgroups) from [`unistd.h`](crate::header::unistd). fn getgroups(list: Out<[gid_t]>) -> Result; /* Note that this is distinct from the legacy POSIX function @@ -128,67 +166,93 @@ pub trait Pal { * page size may be determined through a syscall ("getpagesize"). */ fn getpagesize() -> usize; + /// Platform implementation of [`getpgid()`](crate::header::unistd::getpgid) from [`unistd.h`](crate::header::unistd). fn getpgid(pid: pid_t) -> Result; // Always successful + /// Platform implementation of [`getpid()`](crate::header::unistd::getpid) from [`unistd.h`](crate::header::unistd). fn getpid() -> pid_t; // Always successful + /// Platform implementation of [`getppid()`](crate::header::unistd::getppid) from [`unistd.h`](crate::header::unistd). fn getppid() -> pid_t; + /// Platform implementation of [`getpriority()`](crate::header::sys_resource::getpriority) from [`sys/resource.h`](crate::header::sys_resource). fn getpriority(which: c_int, who: id_t) -> Result; + /// Platform implementation of [`getrandom()`](crate::header::sys_random::getrandom) from [`sys/random.h`](crate::header::sys_random). fn getrandom(buf: &mut [u8], flags: c_uint) -> Result; + /// Platform implementation of [`getresgid()`](crate::header::unistd::getresgid) from [`unistd.h`](crate::header::unistd). fn getresgid( rgid: Option>, egid: Option>, sgid: Option>, ) -> Result<()>; + /// Platform implementation of [`getresuid()`](crate::header::unistd::getresuid) from [`unistd.h`](crate::header::unistd). fn getresuid( ruid: Option>, euid: Option>, suid: Option>, ) -> Result<()>; + /// Platform implementation of [`getrlimit()`](crate::header::sys_resource::getrlimit) from [`sys/resource.h`](crate::header::sys_resource). fn getrlimit(resource: c_int, rlim: Out) -> Result<()>; + /// Platform implementation of [`setrlimit()`](crate::header::sys_resource::setrlimit) from [`sys/resource.h`](crate::header::sys_resource). unsafe fn setrlimit(resource: c_int, rlim: *const rlimit) -> Result<()>; + /// Platform implementation of [`getrusage()`](crate::header::sys_resource::getrusage) from [`sys/resource.h`](crate::header::sys_resource). fn getrusage(who: c_int, r_usage: Out) -> Result<()>; + /// Platform implementation of [`getsid()`](crate::header::unistd::getsid) from [`unistd.h`](crate::header::unistd). fn getsid(pid: pid_t) -> Result; // Always successful + /// Platform implementation of `gettid()` (TODO) from [`unistd.h`](crate::header::unistd). fn gettid() -> pid_t; + /// Platform implementation of [`gettimeofday()`](crate::header::sys_time::gettimeofday) from [`sys/time.h`](crate::header::sys_time). fn gettimeofday(tp: Out, tzp: Option>) -> Result<()>; + /// Platform implementation of [`getuid()`](crate::header::unistd::getuid) from [`unistd.h`](crate::header::unistd). fn getuid() -> uid_t; + /// Platform implementation of [`lchown()`](crate::header::unistd::lchown) from [`unistd.h`](crate::header::unistd). fn lchown(path: CStr, owner: uid_t, group: gid_t) -> Result<()>; + /// Platform implementation of [`link()`](crate::header::unistd::link) from [`unistd.h`](crate::header::unistd). fn link(path1: CStr, path2: CStr) -> Result<()>; + /// Platform implementation of [`lseek()`](crate::header::unistd::lseek) from [`unistd.h`](crate::header::unistd). fn lseek(fildes: c_int, offset: off_t, whence: c_int) -> Result; + /// Platform implementation of [`mkdirat()`](crate::header::sys_stat::mkdirat) from [`sys/stat.h`](crate::header::sys_stat). fn mkdirat(fildes: c_int, path: CStr, mode: mode_t) -> Result<()>; + /// Platform implementation of [`mkdir()`](crate::header::sys_stat::mkdir) from [`sys/stat.h`](crate::header::sys_stat). fn mkdir(path: CStr, mode: mode_t) -> Result<()>; + /// Platform implementation of [`mkfifoat()`](crate::header::sys_stat::mkfifoat) from [`sys/stat.h`](crate::header::sys_stat). fn mkfifoat(dir_fd: c_int, path: CStr, mode: mode_t) -> Result<()>; + /// Platform implementation of [`mkfifo()`](crate::header::sys_stat::mkfifo) from [`sys/stat.h`](crate::header::sys_stat). fn mkfifo(path: CStr, mode: mode_t) -> Result<()>; + /// Platform implementation of [`mknodat()`](crate::header::sys_stat::mknodat) from [`sys/stat.h`](crate::header::sys_stat). fn mknodat(fildes: c_int, path: CStr, mode: mode_t, dev: dev_t) -> Result<()>; + /// Platform implementation of [`mknod()`](crate::header::sys_stat::mknod) from [`sys/stat.h`](crate::header::sys_stat). fn mknod(path: CStr, mode: mode_t, dev: dev_t) -> Result<()>; + /// Platform implementation of [`mlock()`](crate::header::sys_mman::mlock) from [`sys/mman.h`](crate::header::sys_mman). unsafe fn mlock(addr: *const c_void, len: usize) -> Result<()>; + /// Platform implementation of [`mlockall()`](crate::header::sys_mman::mlockall) from [`sys/mman.h`](crate::header::sys_mman). unsafe fn mlockall(flags: c_int) -> Result<()>; + /// Platform implementation of [`mmap()`](crate::header::sys_mman::mmap) from [`sys/mman.h`](crate::header::sys_mman). unsafe fn mmap( addr: *mut c_void, len: usize, @@ -198,6 +262,7 @@ pub trait Pal { off: off_t, ) -> Result<*mut c_void>; + /// Platform implementation of [`mremap()`](crate::header::sys_mman::mremap) from [`sys/mman.h`](crate::header::sys_mman). unsafe fn mremap( addr: *mut c_void, len: usize, @@ -206,47 +271,70 @@ pub trait Pal { args: *mut c_void, ) -> Result<*mut c_void>; + /// Platform implementation of [`mprotect()`](crate::header::sys_mman::mprotect) from [`sys/mman.h`](crate::header::sys_mman). unsafe fn mprotect(addr: *mut c_void, len: usize, prot: c_int) -> Result<()>; + /// Platform implementation of [`msync()`](crate::header::sys_mman::msync) from [`sys/mman.h`](crate::header::sys_mman). unsafe fn msync(addr: *mut c_void, len: usize, flags: c_int) -> Result<()>; + /// Platform implementation of [`munlock()`](crate::header::sys_mman::munlock) from [`sys/mman.h`](crate::header::sys_mman). unsafe fn munlock(addr: *const c_void, len: usize) -> Result<()>; + /// Platform implementation of [`madvise()`](crate::header::sys_mman::madvise) from [`sys/mman.h`](crate::header::sys_mman). unsafe fn madvise(addr: *mut c_void, len: usize, flags: c_int) -> Result<()>; + /// Platform implementation of [`munlockall()`](crate::header::sys_mman::munlockall) from [`sys/mman.h`](crate::header::sys_mman). unsafe fn munlockall() -> Result<()>; + /// Platform implementation of [`munmap()`](crate::header::sys_mman::munmap) from [`sys/mman.h`](crate::header::sys_mman). unsafe fn munmap(addr: *mut c_void, len: usize) -> Result<()>; + /// Platform implementation of [`nanosleep()`](crate::header::time::nanosleep) from [`time.h`](crate::header::time). unsafe fn nanosleep(rqtp: *const timespec, rmtp: *mut timespec) -> Result<()>; + /// Platform implementation of [`open()`](crate::header::fcntl::open) from [`fcntl.h`](crate::header::fcntl). fn open(path: CStr, oflag: c_int, mode: mode_t) -> Result; + /// Platform implementation of `openat()` (TODO) from [`fcntl.h`](crate::header::fcntl). fn openat(dirfd: c_int, path: CStr, oflag: c_int, mode: mode_t) -> Result; + /// Platform implementation of [`pipe2()`](crate::header::unistd::pipe2) from [`unistd.h`](crate::header::unistd). fn pipe2(fildes: Out<[c_int; 2]>, flags: c_int) -> Result<()>; + /// Platform implementation of [`posix_fallocate()`](crate::header::fcntl::posix_fallocate) from [`fcntl.h`](crate::header::fcntl). fn posix_fallocate(fd: c_int, offset: u64, length: NonZeroU64) -> Result<()>; + /// Platform implementation of [`posix_getdents()`](crate::header::dirent::posix_getdents) from [`dirent.h`](crate::header::dirent). fn posix_getdents(fildes: c_int, buf: &mut [u8]) -> Result; unsafe fn rlct_clone( stack: *mut usize, os_specific: &mut OsSpecific, ) -> Result; + unsafe fn rlct_kill(os_tid: pthread::OsTid, signal: usize) -> Result<()>; fn current_os_tid() -> pthread::OsTid; + /// Platform implementation of [`read()`](crate::header::unistd::read) from [`unistd.h`](crate::header::unistd). fn read(fildes: c_int, buf: &mut [u8]) -> Result; + + /// Platform implementation of [`pread()`](crate::header::unistd::pread) from [`unistd.h`](crate::header::unistd). fn pread(fildes: c_int, buf: &mut [u8], offset: off_t) -> Result; + /// Platform implementation of [`readlink()`](crate::header::unistd::readlink) from [`unistd.h`](crate::header::unistd). fn readlink(pathname: CStr, out: &mut [u8]) -> Result; + /// Platform implementation of [`readlinkat()`](crate::header::unistd::readlinkat) from [`unistd.h`](crate::header::unistd). fn readlinkat(dirfd: c_int, pathname: CStr, out: &mut [u8]) -> Result; + /// Platform implementation of [`rename()`](crate::header::stdio::rename) from [`stdio.h`](crate::header::stdio). fn rename(old: CStr, new: CStr) -> Result<()>; + + /// Platform implementation of [`renameat()`](crate::header::stdio::renameat) from [`stdio.h`](crate::header::stdio). fn renameat(old_dir: c_int, old_path: CStr, new_dir: c_int, new_path: CStr) -> Result<()>; + + /// Platform implementation of [`renameat2()`](crate::header::stdio::renameat2) from [`stdio.h`](crate::header::stdio). fn renameat2( old_dir: c_int, old_path: CStr, @@ -255,32 +343,46 @@ pub trait Pal { flags: c_uint, ) -> Result<()>; + /// Platform implementation of [`rmdir()`](crate::header::unistd::rmdir) from [`unistd.h`](crate::header::unistd). fn rmdir(path: CStr) -> Result<()>; + /// Platform implementation of [`sched_yield()`](crate::header::sched::sched_yield) from [`sched.h`](crate::header::sched). fn sched_yield() -> Result<()>; + /// Platform implementation of [`setgroups()`](crate::header::unistd::setgroups) from [`unistd.h`](crate::header::unistd) (TODO: should be `grp.h`?). unsafe fn setgroups(size: size_t, list: *const gid_t) -> Result<()>; + /// Platform implementation of [`setpgid()`](crate::header::unistd::setpgid) from [`unistd.h`](crate::header::unistd). fn setpgid(pid: pid_t, pgid: pid_t) -> Result<()>; + /// Platform implementation of [`setpriority()`](crate::header::sys_resource::setpriority) from [`sys/resource.h`](crate::header::sys_resource). fn setpriority(which: c_int, who: id_t, prio: c_int) -> Result<()>; + /// Platform implementation of [`setresgid()`](crate::header::unistd::setresgid) from [`unistd.h`](crate::header::unistd). fn setresgid(rgid: gid_t, egid: gid_t, sgid: gid_t) -> Result<()>; + /// Platform implementation of [`setresuid()`](crate::header::unistd::setresuid) from [`unistd.h`](crate::header::unistd). fn setresuid(ruid: uid_t, euid: uid_t, suid: uid_t) -> Result<()>; + /// Platform implementation of [`setsid()`](crate::header::unistd::setsid) from [`unistd.h`](crate::header::unistd). fn setsid() -> Result; + /// Platform implementation of [`symlink()`](crate::header::unistd::symlink) from [`unistd.h`](crate::header::unistd). fn symlink(path1: CStr, path2: CStr) -> Result<()>; + /// Platform implementation of [`sync()`](crate::header::unistd::sync) from [`unistd.h`](crate::header::unistd). fn sync() -> Result<()>; + /// Platform implementation of [`timer_create()`](crate::header::time::timer_create) from [`time.h`](crate::header::time). fn timer_create(clock_id: clockid_t, evp: &sigevent, timerid: Out) -> Result<()>; + /// Platform implementation of [`timer_delete()`](crate::header::time::timer_delete) from [`time.h`](crate::header::time). fn timer_delete(timerid: timer_t) -> Result<()>; + /// Platform implementation of [`timer_gettime()`](crate::header::time::timer_gettime) from [`time.h`](crate::header::time). fn timer_gettime(timerid: timer_t, value: Out) -> Result<()>; + /// Platform implementation of [`timer_settime()`](crate::header::time::timer_settime) from [`time.h`](crate::header::time). fn timer_settime( timerid: timer_t, flags: c_int, @@ -289,15 +391,22 @@ pub trait Pal { ) -> Result<()>; // Always successful + /// Platform implementation of [`umask()`](crate::header::sys_stat::umask) from [`sys/stat.h`](crate::header::sys_stat). fn umask(mask: mode_t) -> mode_t; + /// Platform implementation of [`uname()`](crate::header::sys_utsname::uname) from [`sys/utsname.h`](crate::header::sys_utsname). fn uname(utsname: Out) -> Result<()>; + /// Platform implementation of [`unlink()`](crate::header::unistd::unlink) from [`unistd.h`](crate::header::unistd). fn unlink(path: CStr) -> Result<()>; + /// Platform implementation of [`waitpid()`](crate::header::sys_wait::waitpid) from [`sys/wait.h`](crate::header::sys_wait). fn waitpid(pid: pid_t, stat_loc: Option>, options: c_int) -> Result; + /// Platform implementation of [`write()`](crate::header::unistd::write) from [`unistd.h`](crate::header::unistd). fn write(fildes: c_int, buf: &[u8]) -> Result; + + /// Platform implementation of [`pwrite()`](crate::header::unistd::pwrite) from [`unistd.h`](crate::header::unistd). fn pwrite(fildes: c_int, buf: &[u8], offset: off_t) -> Result; fn verify() -> bool; diff --git a/src/platform/redox/mod.rs b/src/platform/redox/mod.rs index 44414fa512..c60b6e3e84 100644 --- a/src/platform/redox/mod.rs +++ b/src/platform/redox/mod.rs @@ -102,7 +102,7 @@ macro_rules! path_from_c_str { static CLONE_LOCK: RwLock<()> = RwLock::new(()); -/// Redox syscall implementation of the platform abstraction layer. +/// Redox syscall implementation of [`Pal`]. pub struct Sys; impl Pal for Sys {