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:

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.

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.