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, uint32_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, uint32_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.