Document cspawn

Signed-off-by: Laurent Bercot <ska@appnovation.com>
author: Laurent Bercot <ska-skaware@skarnet.org> 2023-09-09 14:10:40 +0000
committer: Laurent Bercot <ska@appnovation.com> 2023-09-09 14:10:40 +0000
commit: 8ba811fb48d666a23d60a5ce3a947dcac7baf6ea (patch)
tree: 46f48947eff440efacf739b3f7d6a18744ff7226 /doc/libstddjb
parent: ab2813a10a7fe6edbbef2acdfd22c0666171f566 (diff)
download: skalibs-8ba811fb48d666a23d60a5ce3a947dcac7baf6ea.tar.xz
3 files changed, 133 insertions, 45 deletions
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 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>skalibs: the cspawn library interface</title>
+    <meta name="Description" content="skalibs: the cspawn library interface" />
+    <meta name="Keywords" content="skalibs c unix cspawn fork posix_spawn child process exec library libstddjb" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">libstddjb</a><br />
+<a href="../libskarnet.html">libskarnet</a><br />
+<a href="../index.html">skalibs</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>cspawn</tt> library interface </h1>
+
+<p>
+ The following functions are declared in the <tt>skalibs/cspawn.h</tt> header,
+and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
+</p>
+
+<h2> General information </h2>
+
+<p>
+ <tt>cspawn</tt> is a unifier API to spawn child processes with
+<a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_spawn.html">posix_spawn()</a>
+as a backend if supported by the system, falling back on
+<a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/fork.html">fork()</a> +
+<a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/execve.html">execve()</a>
+otherwise.
+</p>
+
+<h2> Functions </h2>
+
+<h3> Primitive </h3>
+
+<p>
+<code> pid_t cspawn (char const *file, char const *const *argv, char const *const *envp, uint32_t flags, cspawn_fileaction const *fa, size_t n) </code> <br />
+Forks and execs a child as with <tt>exec_ae(file, argv, envp)</tt>.
+Returns 0 if it fails, and the pid of the child if it succeeds.
+Before execing, the following operations are performed in the child:
+</p>
+
+<ul>
+ <li> If <em>flags</em> contains (the or-able value) CSPAWN_FLAGS_SIGBLOCKNONE,
+the child's signal processing mask is reset - no signal will be blocked. </li>
+ <li> Alternatively, if <em>flags</em> contains (the or-able value) CSPAWN_FLAGS_SELFPIPE_FINISH,
+the child's signal state is reset to what it was before the invocation of
+<tt>selfpipe_init()</tt> in the parent. </li>
+ <li> The file actions described in the array <em>fa</em>, which must have at least <em>n</em> elements,
+are processed in order. For every <em>i</em> from 0 to <em>n</em>-1:
+  <ul>
+    <li> if <tt>fa[i].type</tt> is CSPAWN_FA_CLOSE, then file descriptor <tt>fa[i].x.fd</tt> is closed </li>
+    <li> else if <tt>fa[i].type</tt> is CSPAWN_FA_MOVE, then file descriptor <tt>fa[i].x.fd2[1]</tt>
+is moved to <tt>fa[i].x.fd2[0]</tt> </li>
+    <li> else if <tt>fa[i].type</tt> is CSPAWN_FA_COPY, then file descriptor <tt>fa[i].x.fd2[1]</tt>
+is copied to <tt>fa[i].x.fd2[0]</tt>, as with <tt>dup2(fa[i].x.fd2[1], fa[i].x.fd2[0])</tt> </li>
+    <li> else if <tt>fa[i].type</tt> is CSPAWN_FA_OPEN, then file <tt>fa[i].x.openinfo.file</tt> is
+opened with flags <tt>fa[i].x.openinfo.oflag</tt> and mode <tt>fa[i].x.openinfo.mode</tt>, and file
+descriptor <tt>fa[i].x.openinfo.fd</tt> points to it. </li>
+  </ul> </li>
+</ul>
+
+<h3> Higher level interfaces </h3>
+
+<p>
+<code> pid_t child_spawn1_pipe (char const *file, char const *const *argv, char const *const *envp, int *fd, int w) </code> <br />
+Spawns <em>file</em> as with <tt>cspawn()</tt> with a <em>flags</em> value of CSPAWN_FLAGS_SIGBLOCKNONE;
+a pipe is created between the child's
+stdin (if <em>w</em> is 0) or stdout (if <em>w</em> is nonzero) and the parent.
+The parent's end of the pipe will be stored in *<em>fd</em>.
+</p>
+
+<p>
+<code> pid_t child_spawn1_socket (char const *file, char const *const *argv, char const *const *envp, int *fd) </code> <br />
+Like <tt>child_spawn1</tt>, 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 *<em>fd</em>.
+</p>
+
+<p>
+<code> pid_t child_spawn2 (char const *file, char const *const *argv, char const *const *envp, int *fds) </code> <br />
+Two pipes are created between the
+parent and the child. <em>fds</em> must point to an array of 2 ints: this
+array is read as well as written by <tt>child_spawn2()</tt>. On function
+call, the numbers in <em>fds</em> 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, <em>fds</em>
+must contain 0 and 1). On function return, <em>fds</em> contains the
+descriptors for the pipes that read from / write to the child.
+</p>
+
+<p>
+<code> pid_t child_spawn3 (char const *file, char const *const *argv, char const *const *envp, int *fds) </code> <br />
+Three pipes are created between the
+parent and the child. <em>fds</em> must point to an array of 3 ints: this
+array is read as well as written by <tt>child_spawn2()</tt>. On function
+call, the numbers in <em>fds[0]</em> and <em>fds[1]</em> must describe what fds should be used
+in the child to read from (resp. write to) the parent.
+On function return, <em>fds</em> contains the
+descriptors for the pipes that read from / write to the child. <em>fds[2]</em> 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 <tt>SKALIBS_CHILD_SPAWN_FDS</tt> environment variable.
+</p>
+
+
+<p>
+<code> pid_t child_spawn (char const *file, char const *const *argv, char const *const *envp, int *fds, unsigned int nfds) </code> <br />
+More generic spawning function. <em>fds</em> must point to an array of at least <em>nfds</em> 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.
+</p>
+<ul>
+ <li> If <em>nfds</em> is 0, then the function behaves like <tt>cspawn</tt> with a flags value
+of CSPAWN_FLAGS_SIGBLOCKNONE. </li>
+ <li> If <em>nfds</em> is 1 or more, then <em>fds</em> 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 <em>fds[0]</em>, write on <em>fds[1]</em>,
+then any additional fds are available to it in the <tt>SKALIBS_CHILD_SPAWN_FDS</tt> environment
+variable as a comma-separated list of integers. </li>
+</ul>
+
+</body>
+</html>
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.
 </p>
 
 <p>
-<code> pid_t child_spawn0 (char const *file, char const *const *argv, char const *const *envp) </code> <br />
-Forks and executes a child as with <tt>exec_ae(file, argv, envp)</tt>.
-Returns 0 if it fails, and the pid of the child if it succeeds.
-Implemented via <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_spawn.html">posix_spawn()</a>
-on systems that support it.
+The <tt>child_spawn</tt> family of functions has been moved to the
+<a href="cspawn.html">skalibs/cspawn.h</a> header.
 </p>
 
-<p>
-<code> pid_t child_spawn1_pipe (char const *file, char const *const *argv, char const *const *envp, int *fd, int w) </code> <br />
-Like <tt>child_spawn0()</tt>, except that a pipe is created between the child's
-stdin (if <em>w</em> is 0) or stdout (if <em>w</em> is nonzero) and the parent.
-The parent's end of the pipe will be stored in *<em>fd</em>.
-</p>
-
-<p>
-<code> pid_t child_spawn1_socket (char const *file, char const *const *argv, char const *const *envp, int *fd) </code> <br />
-Like <tt>child_spawn0</tt>, 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 *<em>fd</em>.
-</p>
-
-<p>
-<code> pid_t child_spawn2 (char const *file, char const *const *argv, char const *const *envp, int *fds) </code> <br />
-Like <tt>child_spawn0()</tt>, except that two pipes are created between the
-parent and the child. <em>fds</em> must point to an array of 2 ints: this
-array is read as well as written by <tt>child_spawn2()</tt>. On function
-call, the numbers in <em>fds</em> 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, <em>fds</em>
-must contain 0 and 1). On function return, <em>fds</em> contains the
-descriptors for the pipes that read from / write to the child.
-</p>
-
-<p>
-<code> pid_t child_spawn (char const *file, char const *const *argv, char const *const *envp, int *fds, unsigned int nfds) </code> <br />
-More generic spawning function. <em>fds</em> must point to an array of at least <em>nfds</em> 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.
-</p>
-<ul>
- <li> If <em>nfds</em> is 0, then the function behaves like <tt>child_spawn0</tt>, except
-all ignored signals will be un-ignored in the child </li>
- <li> If <em>nfds</em> is 1 or more, then <em>fds</em> will contain pipes between the
-child and the parent. The parent will read on even-numbered ones (starting on <em>fds</em>[0])
-and write on odd-numbered ones. </li>
-</ul>
-
 <h3> Waiting for children </h3>
 
 <p>
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</a> around I/O functions, extra I/O functions </li>
 <a href="https://en.wikipedia.org/wiki/Cdb_%28software%29">cdb</a> files </li>
  <li> <a href="cdbmake.html">skalibs/cdbmake.h</a>: how to write
 <a href="https://en.wikipedia.org/wiki/Cdb_%28software%29">cdb</a> files </li>
+ <li> <a href="cspawn.html">skalibs/cspawn.h</a>: child spawning primitives that use posix_spawn instead of fork when supported </li>
  <li> <a href="direntry.html">skalibs/direntry.h</a>: portable directory operations </li>
  <li> <a href="djbtime.html">skalibs/djbtime.h</a>: conversions between date and time formats </li>
  <li> <a href="djbunix.html">skalibs/djbunix.h</a>: management of basic Unix concepts </li>
author	Laurent Bercot <ska-skaware@skarnet.org>	2023-09-09 14:10:40 +0000
committer	Laurent Bercot <ska@appnovation.com>	2023-09-09 14:10:40 +0000
commit	8ba811fb48d666a23d60a5ce3a947dcac7baf6ea (patch)
tree	46f48947eff440efacf739b3f7d6a18744ff7226 /doc/libstddjb
parent	ab2813a10a7fe6edbbef2acdfd22c0666171f566 (diff)
download	skalibs-8ba811fb48d666a23d60a5ce3a947dcac7baf6ea.tar.xz