From 35425db05e1a70f5d3dd89a66bc5e35be19887c7 Mon Sep 17 00:00:00 2001 From: auronandace Date: Wed, 17 Jun 2026 13:07:08 +0100 Subject: [PATCH] add descriptions to the spawn header functions --- src/header/spawn/file_actions.rs | 107 +++++++++++++++------ src/header/spawn/mod.rs | 56 ++++++++--- src/header/spawn/spawn_attr.rs | 160 +++++++++++++++++++++++++------ 3 files changed, 252 insertions(+), 71 deletions(-) diff --git a/src/header/spawn/file_actions.rs b/src/header/spawn/file_actions.rs index 31cc7d60a3..ffdf82e382 100644 --- a/src/header/spawn/file_actions.rs +++ b/src/header/spawn/file_actions.rs @@ -22,6 +22,7 @@ pub enum Action { struct FileActions(Vec); +/// A spawn file actions object. #[repr(C)] #[derive(Debug, Clone, Copy)] pub struct posix_spawn_file_actions_t { @@ -30,6 +31,7 @@ pub struct posix_spawn_file_actions_t { } impl posix_spawn_file_actions_t { + /// Adds an `Action` to `posix_spawn_file_actions_t`. pub fn add_action(&mut self, action: Action) { let v = ptr::from_mut(self).cast::(); unsafe { @@ -72,8 +74,14 @@ impl IntoIterator for &posix_spawn_file_actions_t { } } -/// See +/// See . /// +/// Initializes the object referenced by `file_actions` to contain no file +/// actions for `posix_spawn()` or `posix_spawnp()` to perform. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `file_actions` is `NULL`. #[unsafe(no_mangle)] pub extern "C" fn posix_spawn_file_actions_init( @@ -90,16 +98,25 @@ pub extern "C" fn posix_spawn_file_actions_init( 0 } -/// See +/// See . /// +/// Destroys the object referenced by `file_actions`, effectively making it +/// uninitialized. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `file_actions` is `NULL`. /// -/// # Safety: -/// If `file_actions` is not `NULL`, then it must be a pointer to a `file_actions` object that was initialised by calling `posix_spawn_file_actions_init`. +/// # Safety +/// If `file_actions` is not `NULL`, then it must be a pointer to a +/// `file_actions` object that was initialised by calling +/// `posix_spawn_file_actions_init()`. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawn_file_actions_destroy( file_actions: *mut posix_spawn_file_actions_t, ) -> c_int { + // TODO should we be returning EINVAL when `file_actions` is invalid? if file_actions.is_null() { panic!("file_actions cannot be NULL"); } @@ -109,26 +126,31 @@ pub unsafe extern "C" fn posix_spawn_file_actions_destroy( 0 } -/// See +/// See . /// +/// Adds an open action to a spawn file actions object. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `file_actions` is `NULL`. /// -/// # Safety: +/// # Safety /// `path` must be a valid null-terminated C string. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawn_file_actions_addopen( file_actions: *mut posix_spawn_file_actions_t, - fd: c_int, + fildes: c_int, path: *const c_char, oflag: c_int, mode: mode_t, ) -> c_int { let file_actions = unsafe { file_actions.as_mut().expect("file_actions cannot be NULL") }; - if fd < 0 { + if fildes < 0 { return EBADF; } file_actions.add_action(Action::Open { - fd, + fd: fildes, path: if path.is_null() { CString::new("").unwrap() } else { @@ -140,31 +162,44 @@ pub unsafe extern "C" fn posix_spawn_file_actions_addopen( 0 } -/// See +/// See . /// +/// Adds a close action to a spawn file actions object. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `file_actions` is `NULL`. /// -/// # Safety: +/// # Safety /// `file_actions` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawn_file_actions_addclose( file_actions: *mut posix_spawn_file_actions_t, - fd: c_int, + fildes: c_int, ) -> c_int { let file_actions = unsafe { file_actions.as_mut().expect("file_actions cannot be NULL") }; - if fd < 0 { + if fildes < 0 { return EBADF; } - file_actions.add_action(Action::Close(fd)); + file_actions.add_action(Action::Close(fildes)); 0 } -/// See +/// See . /// +/// Adds a chdir action to the object referenced by `file_actions` that shall +/// cause the working directory to be set to `path` (as if `chdir(path)` had +/// been called) when a new process is spawned using this file actions object. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `file_actions` is `NULL`. /// -/// # Safety: -/// `file_actions` must be initialised and `path` must be a valid null-terminated C string. +/// # Safety +/// `file_actions` must be initialised and `path` must be a valid +/// null-terminated C string. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawn_file_actions_addchdir( file_actions: *mut posix_spawn_file_actions_t, @@ -181,41 +216,57 @@ pub unsafe extern "C" fn posix_spawn_file_actions_addchdir( 0 } -/// See +/// See . /// +/// Adds a fchdir action to the object referenced by `file_actions` that shall +/// cause the working directory to be set to `fildes` (as if `fchdir(fildes)` +/// had been called) when a new process is spawned using this file actions +/// object. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `file_actions` is `NULL`. /// -/// # Safety: +/// # Safety /// `file_actions` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawn_file_actions_addfchdir( file_actions: *mut posix_spawn_file_actions_t, - fd: c_int, + fildes: c_int, ) -> c_int { let file_actions = unsafe { file_actions.as_mut().expect("file_actions cannot be NULL") }; - if fd < 0 { + if fildes < 0 { return EBADF; } - file_actions.add_action(Action::FChdir(fd)); + file_actions.add_action(Action::FChdir(fildes)); 0 } -/// See +/// See . /// +/// Adds a dup2 action to the object referenced by `file_actions` that shall +/// cause the file descriptor `fildes` to be duplicated as `newfildes` (as if +/// `dup2(fildes, newfildes)` had been called) when a new process is spawned +/// using this file actions object. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `file_actions` is `NULL`. /// -/// # Safety: +/// # Safety /// `file_actions` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawn_file_actions_adddup2( file_actions: *mut posix_spawn_file_actions_t, - fd: c_int, - new: c_int, + fildes: c_int, + newfildes: c_int, ) -> c_int { let file_actions = unsafe { file_actions.as_mut().expect("file_actions cannot be NULL") }; - if fd < 0 || new < 0 { + if fildes < 0 || newfildes < 0 { return EBADF; } - file_actions.add_action(Action::Dup2(fd, new)); + file_actions.add_action(Action::Dup2(fildes, newfildes)); 0 } diff --git a/src/header/spawn/mod.rs b/src/header/spawn/mod.rs index ba3e13e225..08ebe4a108 100644 --- a/src/header/spawn/mod.rs +++ b/src/header/spawn/mod.rs @@ -114,14 +114,29 @@ unsafe fn spawn( Ok(()) } -/// See +/// See . /// -/// `argv` must **not** be `NULL` and must contain atleast the program name. `path` must also be **not** `NULL`. Failure to ensure any of this will result in a panic. +/// Creates a new process (child process) from the specified process image. The +/// `path` argument is a pathname that identifies the new process image file to +/// execute. /// -/// # Safety: -/// `file_actions` and `attrp` must either be `NULL` or be pointers to properly initialised objects. Doing otherwise is undefined behaviour. +/// Returns the process ID of the child process to the parent process, in the +/// variable pointed to by a non-null `pid` argument, and shall return `0` as +/// the function return value. Upon error, an error number shall be returned +/// as the function return value. /// -/// `path` and the elements in `argv` must be a pointers to valid null-terminated character arrays. Failure to ensure any of this will result in undefined behaviour. +/// # Panics +/// `argv` must **not** be `NULL` and must contain atleast the program name. +/// `path` must also **not** be `NULL`. Failure to ensure any of this will +/// result in a panic. +/// +/// # Safety +/// `file_actions` and `attrp` must either be `NULL` or be pointers to properly +/// initialised objects. Doing otherwise is undefined behaviour. +/// +/// `path` and the elements in `argv` must be a pointers to valid +/// null-terminated character arrays. Failure to ensure any of this will result +/// in undefined behaviour. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawn( pid: *mut pid_t, @@ -165,18 +180,33 @@ pub unsafe extern "C" fn posix_spawn( 0 } -/// See +/// See . /// -/// `argv` must **not** be `NULL` and must contain atleast the program name. `path` must also be **not** `NULL`. Failure to ensure any of this will result in a panic. +/// Creates a new process (child process) from the specified process image. The +/// `file` argument is used to construct a pathname that identifies the new +/// process image file. /// -/// # Safety: -/// `file_actions` and `attrp` must either be `NULL` or be pointers to properly initialised objects. Doing otherwise is undefined behaviour. +/// Returns the process ID of the child process to the parent process, in the +/// variable pointed to by a non-null `pid` argument, and shall return `0` as +/// the function return value. Upon error, an error number shall be returned +/// as the function return value. /// -/// `path` and the elements in `argv` must be a pointers to valid null-terminated character arrays. Failure to ensure any of this will result in undefined behaviour. +/// # Panics +/// `argv` must **not** be `NULL` and must contain atleast the program name. +/// `file` must also **not** be `NULL`. Failure to ensure any of this will +/// result in a panic. +/// +/// # Safety +/// `file_actions` and `attrp` must either be `NULL` or be pointers to properly +/// initialised objects. Doing otherwise is undefined behaviour. +/// +/// `file` and the elements in `argv` must be a pointers to valid +/// null-terminated character arrays. Failure to ensure any of this will result +/// in undefined behaviour. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnp( pid: *mut pid_t, - path: *const c_char, + file: *const c_char, file_actions: *const posix_spawn_file_actions_t, attrp: *const posix_spawnattr_t, argv: *const *mut c_char, @@ -194,9 +224,9 @@ pub unsafe extern "C" fn posix_spawnp( }; let envp = unsafe { NulTerminated::new(envp) }; let program = unsafe { - CStr::from_ptr(path) + CStr::from_ptr(file) .to_str() - .expect("path cannot be NULL") + .expect("file cannot be NULL") .to_string() }; diff --git a/src/header/spawn/spawn_attr.rs b/src/header/spawn/spawn_attr.rs index b6edda0c86..c6d0f0b08c 100644 --- a/src/header/spawn/spawn_attr.rs +++ b/src/header/spawn/spawn_attr.rs @@ -31,6 +31,7 @@ pub const POSIX_SPAWN_SETSIGMASK: c_short = 4; pub const POSIX_SPAWN_SETSCHEDPARAM: c_short = 5; pub const POSIX_SPAWN_SETSCHEDULER: c_short = 6; +/// A spawn attributes object. #[repr(C)] pub struct posix_spawnattr_t { pub param: sched_param, @@ -41,9 +42,15 @@ pub struct posix_spawnattr_t { pub sigmask: sigset_t, } -/// See +/// See . /// -/// Panics is `attr` is `NULL`. +/// Initializes a spawn attributes object `attr` with a default value for all +/// the individual attributes used by the implementation. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics +/// Panics if `attr` is `NULL`. #[unsafe(no_mangle)] pub extern "C" fn posix_spawnattr_init(attr: *mut posix_spawnattr_t) -> c_int { unsafe { @@ -53,60 +60,89 @@ pub extern "C" fn posix_spawnattr_init(attr: *mut posix_spawnattr_t) -> c_int { 0 } -/// See +/// See . /// -/// Panics is `attr` is `NULL`. +/// Destroys a spawn attributes object. /// -/// # Safety: -/// `attr` must be a pointer to `posix_spawnattr_t` and must at least be initialised. +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics +/// Panics if `attr` is `NULL`. +/// +/// # Safety +/// `attr` must be a pointer to `posix_spawnattr_t` and must at least be +/// initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_destroy(attr: *mut posix_spawnattr_t) -> c_int { unsafe { + // TODO should we be returning EINVAL when `attr` is invalid? let attr = attr.as_mut().expect("posix_spawnattr_t cannot be NULL"); *attr = zeroed(); } 0 } -/// See +/// See . /// +/// Sets the spawn-schedparam attribute in an initialized attributes object +/// referenced by `attr`. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` or `schedparam` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_setschedparam( attr: *mut posix_spawnattr_t, schedparam: *const sched_param, ) -> c_int { + // TODO should we be returning EINVAL when `attr` is invalid? let attr = unsafe { attr.as_mut().expect("posix_spawnattr_t cannot be NULL") }; let schedparam = unsafe { schedparam.as_ref().expect("schedparam cannot be NULL") }; attr.param = *schedparam; 0 } -/// See +/// See . /// +/// Obtains the value of the spawn-schedparam attribute from the attributes +/// object referenced by `attr`. +/// +/// Upon success, returns `0` and stores the value of the spawn-schedparam +/// attribute of `attr` into the object referenced by `schedparam`. Upon +/// failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` or `schedparam` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_getschedparam( attr: *const posix_spawnattr_t, schedparam: *mut sched_param, ) -> c_int { + // TODO should we be returning EINVAL when `attr` is invalid? let attr = unsafe { attr.as_ref().expect("posix_spawnattr_t cannot be NULL") }; let schedparam = unsafe { schedparam.as_mut().expect("schedparam cannot be NULL") }; *schedparam = attr.param; 0 } -/// See +/// See . /// +/// Sets the spawn-schedpolicy attribute in an initialized attributes object +/// referenced by `attr`. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_setschedpolicy( @@ -122,11 +158,19 @@ pub unsafe extern "C" fn posix_spawnattr_setschedpolicy( 0 } -/// See +/// See . /// +/// Obtains the value of the spawn-schedpolicy attribute from the attributes +/// object referenced by `attr`. +/// +/// Upon success, returns `0` and stores the value of the spawn-schedpolicy +/// attribute of `attr` into the object referenced by `schedpolicy`. Upon +/// failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` or `schedpolicy` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_getschedpolicy( @@ -139,11 +183,17 @@ pub unsafe extern "C" fn posix_spawnattr_getschedpolicy( 0 } -/// See +/// See . /// +/// Sets the spawn-sigdefault attribute in an initialized attributes object +/// referenced by `attr`. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` or `sigdefault` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_setsigdefault( @@ -156,11 +206,19 @@ pub unsafe extern "C" fn posix_spawnattr_setsigdefault( 0 } -/// See +/// See . /// +/// Obtains the value of the spawn-sigdefault attribute from the attributes +/// object referenced by `attr`. +/// +/// Upon success, returns `0` and stores the value of the spawn-sigdefault +/// attribute of `attr` into the object referenced by `sigdefault`. Upon +/// failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` or `sigdefault` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_getsigdefault( @@ -173,11 +231,17 @@ pub unsafe extern "C" fn posix_spawnattr_getsigdefault( 0 } -/// See +/// See . /// +/// Sets the spawn-sigmask attribute in an initialized attributes object +/// referenced by `attr`. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` or `sigmask` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_setsigmask( @@ -190,11 +254,19 @@ pub unsafe extern "C" fn posix_spawnattr_setsigmask( 0 } -/// See +/// See . /// +/// Obtains the value of the spawn-sigmask attribute from the attributes +/// object referenced by `attr`. +/// +/// Upon success, returns `0` and stores the value of the spawn-sigmask +/// attribute of `attr` into the object referenced by `sigmask`. Upon +/// failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` or `sigmask` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_getsigmask( @@ -207,11 +279,17 @@ pub unsafe extern "C" fn posix_spawnattr_getsigmask( 0 } -/// See +/// See . /// +/// Sets the spawn-flags attribute in an initialized attributes object +/// referenced by `attr`. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_setflags( @@ -229,11 +307,19 @@ pub unsafe extern "C" fn posix_spawnattr_setflags( 0 } -/// See +/// See . /// +/// Obtains the value of the spawn-flags attribute from the attributes +/// object referenced by `attr`. +/// +/// Upon success, returns `0` and stores the value of the spawn-flags +/// attribute of `attr` into the object referenced by `flags`. Upon +/// failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` or `flags` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_getflags( @@ -247,11 +333,17 @@ pub unsafe extern "C" fn posix_spawnattr_getflags( 0 } -/// See +/// See . /// +/// Sets the spawn-pgroup attribute in an initialized attributes object +/// referenced by `attr`. +/// +/// Upon success, returns `0`. Upon failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_setpgroup( @@ -263,11 +355,19 @@ pub unsafe extern "C" fn posix_spawnattr_setpgroup( 0 } -/// See +/// See . /// +/// Obtains the value of the spawn-pgroup attribute from the attributes +/// object referenced by `attr`. +/// +/// Upon success, returns `0` and stores the value of the spawn-pgroup +/// attribute of `attr` into the object referenced by `pgroup`. Upon +/// failure, an error number is returned. +/// +/// # Panics /// Panics if `attr` or `pgroup` is `NULL`. /// -/// # Safety: +/// # Safety /// `attr` must be initialised. #[unsafe(no_mangle)] pub unsafe extern "C" fn posix_spawnattr_getpgroup(