skalibs: the cspawn library interface
Keywords: skalibs c unix cspawn fork posix_spawn child process exec library libstddjb

libstddjb
libskarnet
skalibs
Software
skarnet.org

# The `cspawn` library interface

The following functions are declared in the `skalibs/cspawn.h` header, and implemented in the `libskarnet.a` or `libskarnet.so` library.

## General information

`cspawn` is a unifier API to spawn child processes with posix_spawn() as a backend if supported by the system, falling back on fork() + execve() otherwise.

## Functions

### Primitive

`pid_t cspawn (char const *file, char const *const *argv, char const *const *envp, uint16_t flags, cspawn_fileaction const *fa, size_t n)`
Forks and execs a child as with `exec_ae(file, argv, envp)`. Returns 0 if it fails, and the pid of the child if it succeeds. Before execing, the following operations are performed in the child:

- If flags contains (the or-able value) CSPAWN_FLAGS_SIGBLOCKNONE, the child's signal processing mask is reset - no signal will be blocked.
- Alternatively, if flags contains (the or-able value) CSPAWN_FLAGS_SELFPIPE_FINISH, the child's signal state is reset to what it was before the invocation of `selfpipe_init()` in the parent.
- The file actions described in the array fa, which must have at least n elements, are processed in order. For every i from 0 to n-1:
  - if `fa[i].type` is CSPAWN_FA_CLOSE, then file descriptor `fa[i].x.fd` is closed
  - else if `fa[i].type` is CSPAWN_FA_MOVE, then file descriptor `fa[i].x.fd2[1]` is moved to `fa[i].x.fd2[0]`
  - else if `fa[i].type` is CSPAWN_FA_COPY, then file descriptor `fa[i].x.fd2[1]` is copied to `fa[i].x.fd2[0]`, as with `dup2(fa[i].x.fd2[1], fa[i].x.fd2[0])`
  - else if `fa[i].type` is CSPAWN_FA_OPEN, then file `fa[i].x.openinfo.file` is opened with flags `fa[i].x.openinfo.oflag` and mode `fa[i].x.openinfo.mode`, and file descriptor `fa[i].x.openinfo.fd` points to it.

### Higher level interfaces

`pid_t child_spawn1_pipe (char const *file, char const *const *argv, char const *const *envp, int *fd, int w)`
Spawns file as with `cspawn()` with a flags value of CSPAWN_FLAGS_SIGBLOCKNONE; a pipe is created between the child's stdin (if w is 0) or stdout (if w is nonzero) and the parent. The parent's end of the pipe will be stored in *fd.

`pid_t child_spawn1_socket (char const *file, char const *const *argv, char const *const *envp, int *fd)`
Like `child_spawn1`, except that a socket, not a pipe is created between the parent and the child. Both the child's stdin and stdout point to the socket; the parent has its end of the socket available in *fd.

`pid_t child_spawn2 (char const *file, char const *const *argv, char const *const *envp, int *fds)`
Two pipes are created between the parent and the child. fds must point to an array of 2 ints: this array is read as well as written by `child_spawn2()`. On function call, the numbers in fds must describe what fds should be used in the child to contain the communication pipes (for instance, if the child will read from its parent on stdin and write to its parent on stdout, fds must contain 0 and 1). On function return, fds contains the descriptors for the pipes that read from / write to the child.

`pid_t child_spawn3 (char const *file, char const *const *argv, char const *const *envp, int *fds)`
Three pipes are created between the parent and the child. fds must point to an array of 3 ints: this array is read as well as written by `child_spawn2()`. On function call, the numbers in fds[0] and fds[1] must describe what fds should be used in the child to read from (resp. write to) the parent. On function return, fds contains the descriptors for the pipes that read from / write to the child. fds[2] is the reading end of a pipe; the writing end is present in the child, and its number is available as the value of the `SKALIBS_CHILD_SPAWN_FDS` environment variable.

`pid_t child_spawn (char const *file, char const *const *argv, char const *const *envp, int *fds, unsigned int nfds)`
More generic spawning function. fds must point to an array of at least nfds ints; file descriptors reading from or writing to the child will be stored there. The function returns 0 on failure or the pid of the child on success.

- If nfds is 0, then the function behaves like `cspawn` with a flags value of CSPAWN_FLAGS_SIGBLOCKNONE.
- If nfds is 1 or more, then fds will contain pipes between the child and the parent. The parent will read on even-numbered ones and write on odd-numbered ones. The child will read on fds[0], write on fds[1], then any additional fds are available to it in the `SKALIBS_CHILD_SPAWN_FDS` environment variable as a comma-separated list of integers.

`pid_t gcspawn (char const *file, char const *const *argv, char const *const *envp, uint16_t flags, cspawn_fileaction const *fa, size_t n)`
Like `cspawn`, but argv will be running as a grandchild of the current process. The function forks once, invokes `cspawn` from the child, and the child exits after passing the grandchild's pid to the parent.