From 8ba811fb48d666a23d60a5ce3a947dcac7baf6ea Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 9 Sep 2023 14:10:40 +0000 Subject: Document cspawn Signed-off-by: Laurent Bercot --- doc/libstddjb/cspawn.html | 130 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 doc/libstddjb/cspawn.html (limited to 'doc/libstddjb/cspawn.html') diff --git a/doc/libstddjb/cspawn.html b/doc/libstddjb/cspawn.html new file mode 100644 index 0000000..53ca535 --- /dev/null +++ b/doc/libstddjb/cspawn.html @@ -0,0 +1,130 @@ + + + + + + skalibs: the cspawn library interface + + + + + + +

+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: +

+ + + +

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. +

+ + + + -- cgit v1.2.3