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 +++++++++++++++++++++++++++++++++++++++++++++ doc/libstddjb/djbunix.html | 47 +--------------- doc/libstddjb/index.html | 1 + 3 files changed, 133 insertions(+), 45 deletions(-) create mode 100644 doc/libstddjb/cspawn.html (limited to 'doc/libstddjb') 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. +

+ + + + diff --git a/doc/libstddjb/djbunix.html b/doc/libstddjb/djbunix.html index a892bde..6989be7 100644 --- a/doc/libstddjb/djbunix.html +++ b/doc/libstddjb/djbunix.html @@ -357,53 +357,10 @@ and the grandchild's PID if the current process is the parent.

- pid_t child_spawn0 (char const *file, char const *const *argv, char const *const *envp)
-Forks and executes a child as with exec_ae(file, argv, envp). -Returns 0 if it fails, and the pid of the child if it succeeds. -Implemented via posix_spawn() -on systems that support it. +The child_spawn family of functions has been moved to the +skalibs/cspawn.h header.

-

- pid_t child_spawn1_pipe (char const *file, char const *const *argv, char const *const *envp, int *fd, int w)
-Like child_spawn0(), except that 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_spawn0, except that a socket 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)
-Like child_spawn0(), except that 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 writes 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_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. -

- -

Waiting for children

diff --git a/doc/libstddjb/index.html b/doc/libstddjb/index.html index 98dc062..2e25056 100644 --- a/doc/libstddjb/index.html +++ b/doc/libstddjb/index.html @@ -57,6 +57,7 @@ wrappers around I/O functions, extra I/O functions cdb files

  • skalibs/cdbmake.h: how to write cdb files
    • +
  • skalibs/cspawn.h: child spawning primitives that use posix_spawn instead of fork when supported
  • skalibs/direntry.h: portable directory operations
  • skalibs/djbtime.h: conversions between date and time formats
  • skalibs/djbunix.h: management of basic Unix concepts
    • -- cgit v1.3.1