Add manpages for posix_spawn

Author: https://github.com/nico
Commit: https://github.com/SerenityOS/serenity/commit/0d851b1930f
Pull-request: https://github.com/SerenityOS/serenity/pull/2700
Reviewed-by: https://github.com/alimpfard
Reviewed-by: https://github.com/bugaevc

Base/usr/share/man/man2/posix_spawn.md

@@ -0,0 +1,66 @@
+## Name
+
+posix\_spawn - launch a new process
+
+## Synopsis
+
+```**c++
+#include <spawn.h>
+
+int posix_spawn(pid_t* pid, const char* executable_path, const posix_spawn_file_actions_t*, const posix_spawnattr_t*, char* const argv[], char* const envp[]);
+int posix_spawnp(pid_t* pid, const char* executable_path, const posix_spawn_file_actions_t*, const posix_spawnattr_t*, char* const argv[], char* const envp[]);
+```
+
+## Description
+
+Spawn a new process reading the binary `executable_path`, passing `argv` as arguments to `main()` and setting `envp` as argument.
+
+Places the process ID of the new process in `pid`.
+
+If `executable_path` passed to `posix_spawn` is a relative path, it is resolved relative to the current working directory.
+
+If `executable_path` passed to `posix_spawnp` is a relative path, it is resolved by searching through directories specified in the `PATH` environment variable.
+
+The `posix_spawn_file_actions_t` and `posix_spawnattr_t` arguments may be `nullptr`. If they aren't, see [`posix_spawn_file_actions`(2)](posix_spawn_file_actions_init.md) and [`posix_spawnattr`(2)](posix_spawnattr_init.md) for what they do.
+
+The last entry in `argv` and `envp` has to be `nullptr`.
+
+The new process is started as if the following steps are executed in this order:
+
+1. A new process is started as if `fork()` was called.
+2. If the `posix_spawnattr_t` parameter is non-nullptr, it [takes effect](posix_spawnattr_init.md).
+3. If the `posix_spawn_file_actions_t` parameter is non-nullptr, it [takes effect](posix_spawn_file_actions_init.md).
+4. `executable_path` is loaded and starts running, as if `execve` or `execvpe` was called.
+
+## Return value
+
+If the process is successfully forked, returns 0.
+Otherwise, returns an error number. This function does *not* return -1 on error and does *not* set `errno` like most other functions, it instead returns what other functions set `errno` to as result.
+
+If the process forks successfully but spawnattr or file action processing or exec fail, `posix_spawn` returns 0 and the child exits with exit code `127`.
+
+## Example
+
+This simple example launches `/bin/Calculator`.
+
+To make the child process use the parent's environment, it passes `environ` from `unistd.h`.
+
+```**c++
+#include <errno.h>
+#include <unistd.h>
+#include <stdio.h>
+#include <spawn.h>
+
+int main()
+{
+    const char* argv[] = { "Calculator", nullptr };
+    pid_t child_pid;
+    if ((errno = posix_spawn(&child_pid, "/bin/Calculator", nullptr, nullptr, const_cast<char**>(argv), environ)))
+        perror("posix_spawn");
+}
+```
+
+## See also
+
+* [`posix_spawnattr`(2)](posix_spawnattr_init.md)
+* [`posix_spawn_file_actions`(2)](posix_spawn_file_actions_init.md)

Base/usr/share/man/man2/posix_spawn_file_actions_addchdir.md

@@ -0,0 +1 @@
+posix_spawn_file_actions_init.md

Base/usr/share/man/man2/posix_spawn_file_actions_addclose.md

@@ -0,0 +1 @@
+posix_spawn_file_actions_init.md

Base/usr/share/man/man2/posix_spawn_file_actions_adddestroy.md

@@ -0,0 +1 @@
+posix_spawn_file_actions_init.md

Base/usr/share/man/man2/posix_spawn_file_actions_adddup2.md

@@ -0,0 +1 @@
+posix_spawn_file_actions_init.md

Base/usr/share/man/man2/posix_spawn_file_actions_addfchdir.md

@@ -0,0 +1 @@
+posix_spawn_file_actions_init.md

Base/usr/share/man/man2/posix_spawn_file_actions_addopen.md

@@ -0,0 +1 @@
+posix_spawn_file_actions_init.md

Base/usr/share/man/man2/posix_spawn_file_actions_init.md

@@ -0,0 +1,50 @@
+## Name
+
+`posix_spawn_file_actions` - configure file actions for `posix_spawn`
+
+## Synopsis
+
+```**c++
+#include <spawn.h>
+
+typedef struct posix_spawn_file_actions_t;
+
+int posix_spawn_file_actions_init(posix_spawn_file_actions_t*);
+int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t*);
+
+int posix_spawn_file_actions_addchdir(posix_spawn_file_actions_t*, const char*);
+int posix_spawn_file_actions_addfchdir(posix_spawn_file_actions_t*, int);
+int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t*, int);
+int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t*, int old_fd, int new_fd);
+int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t*, int fd, const char*, int flags, mode_t);
+```
+
+## Description
+
+Configure a `posix_spawn_file_actions_t` object for use with [`posix_spawn`(2)](posix_spawn.md). This object can be used to let `posix_spawn()` set up file-related state for the spawned child process. The file actions are executed after creating the the new process but before loading its binary in the order they were added to the `posix_spawn_file_actions_t` object.
+
+A `posix_spawn_file_actions_t` object is allocated on the stack but starts in an undefined state.
+
+`posix_spawn_file_actions_init()` initializes a `posix_spawn_file_actions_t` object that is in an undefined state and puts it in a valid state. It has to be called before the object can be passed to any other function.
+
+`posix_spawn_file_actions_destroy()` frees up resources used by a valid `posix_spawn_file_actions_t` object and puts it into an undefined state. It has to be called after a `posix_spawn_file_actions_t` object is no longer needed.
+
+It is valid to alternatingly call `posix_spawn_file_actions_init()` and `posix_spawn_file_actions_destroy()` on the same object, 
+
+`posix_spawn_file_actions_addchdir()` and `posix_spawn_file_actions_addfchdir()` make `posix_spawn()` change the current working directory before spawning a process, like `chdir` and `fchdir` would.. The current working directory affects the spawned child process, but also relative paths passed to later `posix_spawn_file_actions_add(f)chdir()` and `posix_spawn_file_actions_addopen()`, and relative paths passed to `posix_spawn()` for the executable path.
+
+`posix_spawn_file_actions_addclose()` makes `posix_spawn()` close a file descriptor before spawning a process, like `close` would.
+
+`posix_spawn_file_actions_addclose()` makes `posix_spawn()` dup a file descriptor before spawning a process, like `dup2` would.
+
+`posix_spawn_file_actions_addopen()` makes `posix_spawn()` open a file with given flags and mode, like `open` would, and then makes it available under fd `fd` to the spawned process.
+
+## Return value
+
+In SerenityOS, these functions always succeed and return 0.
+
+If the effect of a file action fails, the child will exit with exit code 127 before even executing the child binary.
+
+## See also
+
+* [`posix_spawn`(2)](posix_spawn.md)

Base/usr/share/man/man2/posix_spawnattr_destroy.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_getflags.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_getpgroup.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_getschedparam.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_getschedpolicy.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_getsigdefault.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_getsigmask.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_init.md

@@ -0,0 +1,78 @@
+## Name
+
+posix\_spawnattr - configure attributes for posix\_spawn
+
+## Synopsis
+
+```**c++
+#include <spawn.h>
+
+POSIX_SPAWN_RESETIDS
+POSIX_SPAWN_SETPGROUP
+POSIX_SPAWN_SETSCHEDPARAM
+POSIX_SPAWN_SETSCHEDULER
+POSIX_SPAWN_SETSIGDEF
+POSIX_SPAWN_SETSIGMASK
+POSIX_SPAWN_SETSID
+
+struct posix_spawnattr_t;
+
+int posix_spawnattr_init(posix_spawnattr_t*);
+int posix_spawnattr_destroy(posix_spawnattr_t*);
+
+int posix_spawnattr_getflags(const posix_spawnattr_t*, short*);
+int posix_spawnattr_getpgroup(const posix_spawnattr_t*, pid_t*);
+int posix_spawnattr_getschedparam(const posix_spawnattr_t*, struct sched_param*);
+int posix_spawnattr_getschedpolicy(const posix_spawnattr_t*, int*);
+int posix_spawnattr_getsigdefault(const posix_spawnattr_t*, sigset_t*);
+int posix_spawnattr_getsigmask(const posix_spawnattr_t*, sigset_t*);
+int posix_spawnattr_setflags(posix_spawnattr_t*, short);
+int posix_spawnattr_setpgroup(posix_spawnattr_t*, pid_t);
+int posix_spawnattr_setschedparam(posix_spawnattr_t*, const struct sched_param*);
+int posix_spawnattr_setschedpolicy(posix_spawnattr_t*, int);
+int posix_spawnattr_setsigdefault(posix_spawnattr_t*, const sigset_t*);
+int posix_spawnattr_setsigmask(posix_spawnattr_t*, const sigset_t*);
+```
+
+## Description
+
+Configures a `posix_spawnattr_t` object for use with [`posix_spawn`(2)](posix_spawn.md). This object can be used to let `posix_spawn()` set up process attributes for the spawned child process. The file actions are executed after creating the new process but before loading its binary.
+
+A `posix_spawnattr_t` object is allocated on the stack but starts in an undefined state.
+
+`posix_spawnattr_init()` initializes a `posix_spawnattr_t` object that is in an undefined state and puts it in a valid state. It has to be called before the object can be passed to any other function.
+
+`posix_spawnattr_destroy()` frees up resources used by a valid `posix_spawn_file_actions_t` object and puts it into an undefined state. It has to be called after a `posix_spawnattr_t` object is no longer needed.
+
+It is valid to alternatingly call `posix_spawnattr_init()` and `posix_spawnattr_destroy()` on the same object, 
+
+`posix_spawnattr_setflags()` configures which attributes of the new child process `posix_spawn()` will set. It receives a bitmask that can contain:
+
+* `POSIX_SPAWN_RESETIDS`: If set, `posix_spawn()` will reset the effective uid and gid of the child process to the real uid and gid of the parent process. See also [`setuid_overview`(7)](../man7/setuid_overview.md).
+
+* `POSIX_SPAWN_SETPGROUP`: If set, `posix_spawn()` will set the process group ID of the child process to the process group ID configured with `posix_spawnattr_setpgroup()`, as if `setpgid(0, pgroup)` was called in the child process. The behavior if both this and `POSIX_SPAWN_SETSID` is set is undefined.
+
+* `POSIX_SPAWN_SETSCHEDPARAM`: If set, `posix_spawn()` will set the scheduler parameter of the child process to the process group ID configured with `posix_spawnattr_setschedparam()`, as if `sched_setparam(0, schedparam)` was called in the child process.
+
+* `POSIX_SPAWN_SETSCHEDULER`: This is not yet implemented in SerenityOS.
+
+* `POSIX_SPAWN_SETSIGDEF`: If set, `posix_spawn()` will reset the signal handlers of the child process configured with `posix_spawnattr_setsigdefault()` to each signal's default handler.
+
+* `POSIX_SPAWN_SETSIGMASK`: If set, `posix_spawn()` will set the signal mask of the child process to the signal mask configured with `posix_spawnattr_setsigmask()`, as if `sigprocmask()` was called in the child process.
+
+* `POSIX_SPAWN_SETSID`: If set, `posix_spawn()` will run the child process in a new session, as if `setsid()` was called in the child process. The behavior if bboth this an d`POSIX_SPAWN_SETPGROUP` is set is undefined.
+
+The `posix_spawnattr_get*` functions return what's been set with the corresponding setters. The default `flags` and `pgroup` are 0, the default `sigdefault` set is `sigemptyset()`, all other fields have an unspecified default value.
+
+
+## Return value
+
+In SerenityOS, these functions always succeed and return 0.
+
+The one exception is `posix_spawnattr_setflags()`, which can return -1 and set `errno` to `EINVAL` if an unknown bit is set in the passed bitmask.
+
+If the effect of an attr fails, the child will exit with exit code 127 before even executing the child binary.
+
+## See also
+
+* [`posix_spawn`(2)](posix_spawn.md)

Base/usr/share/man/man2/posix_spawnattr_setflags.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_setpgroup.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_setschedparam.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_setschedpolicy.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_setsigdefault.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnattr_setsigmask.md

@@ -0,0 +1 @@
+posix_spawnattr_init.md

Base/usr/share/man/man2/posix_spawnp.md

@@ -0,0 +1 @@
+posix_spawn.md

Libraries/LibC/spawn.h

@@ -70,8 +70,8 @@ typedef struct {
     sigset_t sigmask;
 } posix_spawnattr_t;
 
-int posix_spawn(pid_t*, const char*, const posix_spawn_file_actions_t*, const posix_spawnattr_t*, char* const[], char* const[]);
-int posix_spawnp(pid_t*, const char*, const posix_spawn_file_actions_t*, const posix_spawnattr_t*, char* const[], char* const[]);
+int posix_spawn(pid_t*, const char*, const posix_spawn_file_actions_t*, const posix_spawnattr_t*, char* const argv[], char* const envp[]);
+int posix_spawnp(pid_t*, const char*, const posix_spawn_file_actions_t*, const posix_spawnattr_t*, char* const argv[], char* const envp[]);
 
 int posix_spawn_file_actions_addchdir(posix_spawn_file_actions_t*, const char*);
 int posix_spawn_file_actions_addfchdir(posix_spawn_file_actions_t*, int);