Merge branch 'spawn-doc' into 'master'

add descriptions to the spawn header functions

See merge request redox-os/relibc!1473

src/header/spawn/file_actions.rs

@@ -22,6 +22,7 @@ pub enum Action {
 
 struct FileActions(Vec<Action>);
 
+/// 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::<FileActions>();
         unsafe {
@@ -72,8 +74,14 @@ impl IntoIterator for &posix_spawn_file_actions_t {
     }
 }
 
-/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_init.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_init.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_destroy.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_destroy.html>.
 ///
+/// 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:
+/// # 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`.
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_addopen.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_addopen.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_addclose.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_addclose.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_addchdir.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_addchdir.html>.
 ///
+/// 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:
+/// # Safety
-/// `file_actions` must be initialised and `path` must be a valid null-terminated C string.
+/// `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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_addfchdir.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_addfchdir.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_adddup2.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn_file_actions_adddup2.html>.
 ///
+/// 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,
+    fildes: c_int,
-    new: 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
 }

src/header/spawn/mod.rs

@@ -114,14 +114,29 @@ unsafe fn spawn(
     Ok(())
 }
 
-/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn.html>.
 ///
-/// `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:
+/// Returns the process ID of the child process to the parent process, in the
-/// `file_actions` and `attrp` must either be `NULL` or be pointers to properly initialised objects. Doing otherwise is undefined behaviour.
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnp.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnp.html>.
 ///
-/// `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:
+/// Returns the process ID of the child process to the parent process, in the
-/// `file_actions` and `attrp` must either be `NULL` or be pointers to properly initialised objects. Doing otherwise is undefined behaviour.
+/// 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()
     };
 

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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_init.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_init.html>.
 ///
-/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_destroy.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_destroy.html>.
 ///
-/// Panics is `attr` is `NULL`.
+/// Destroys a spawn attributes object.
 ///
-/// # Safety:
+/// Upon success, returns `0`. Upon failure, an error number is returned.
-/// `attr` must be a pointer to `posix_spawnattr_t` and must at least be initialised.
+///
+/// # 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setschedparam.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setschedparam.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getschedparam.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getschedparam.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setschedpolicy.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setschedpolicy.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getschedpolicy.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getschedpolicy.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setsigdefault.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setsigdefault.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getsigdefault.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getsigdefault.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setsigmask.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setsigmask.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getsigmask.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getsigmask.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setflags.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setflags.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getflags.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getflags.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setpgroup.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_setpgroup.html>.
 ///
+/// 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 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getpgroup.html>
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawnattr_getpgroup.html>.
 ///
+/// 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(