cspawn.html (6806B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the cspawn library interface</title> 7 <meta name="Description" content="skalibs: the cspawn library interface" /> 8 <meta name="Keywords" content="skalibs c unix cspawn fork posix_spawn child process exec library libstddjb" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>cspawn</tt> library interface </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/cspawn.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>cspawn</tt> is a unifier API to spawn child processes with 32 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_spawn.html">posix_spawn()</a> 33 as a backend if supported by the system, falling back on 34 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/fork.html">fork()</a> + 35 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/execve.html">execve()</a> 36 otherwise. 37 </p> 38 39 <h2> Functions </h2> 40 41 <h3> Primitive </h3> 42 43 <p> 44 <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> 45 Forks and execs a child as with <tt>exec_ae(file, argv, envp)</tt>. 46 Returns 0 if it fails, and the pid of the child if it succeeds. 47 Before execing, the following operations are performed in the child: 48 </p> 49 50 <ul> 51 <li> If <em>flags</em> contains (the or-able value) CSPAWN_FLAGS_SIGBLOCKNONE, 52 the child's signal processing mask is reset - no signal will be blocked. </li> 53 <li> Alternatively, if <em>flags</em> contains (the or-able value) CSPAWN_FLAGS_SELFPIPE_FINISH, 54 the child's signal state is reset to what it was before the invocation of 55 <tt>selfpipe_init()</tt> in the parent. </li> 56 <li> The file actions described in the array <em>fa</em>, which must have at least <em>n</em> elements, 57 are processed in order. For every <em>i</em> from 0 to <em>n</em>-1: 58 <ul> 59 <li> if <tt>fa[i].type</tt> is CSPAWN_FA_CLOSE, then file descriptor <tt>fa[i].x.fd</tt> is closed </li> 60 <li> else if <tt>fa[i].type</tt> is CSPAWN_FA_MOVE, then file descriptor <tt>fa[i].x.fd2[1]</tt> 61 is moved to <tt>fa[i].x.fd2[0]</tt> </li> 62 <li> else if <tt>fa[i].type</tt> is CSPAWN_FA_COPY, then file descriptor <tt>fa[i].x.fd2[1]</tt> 63 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> 64 <li> else if <tt>fa[i].type</tt> is CSPAWN_FA_OPEN, then file <tt>fa[i].x.openinfo.file</tt> is 65 opened with flags <tt>fa[i].x.openinfo.oflag</tt> and mode <tt>fa[i].x.openinfo.mode</tt>, and file 66 descriptor <tt>fa[i].x.openinfo.fd</tt> points to it. </li> 67 </ul> </li> 68 </ul> 69 70 <h3> Higher level interfaces </h3> 71 72 <p> 73 <code> pid_t child_spawn1_pipe (char const *file, char const *const *argv, char const *const *envp, int *fd, int w) </code> <br> 74 Spawns <em>file</em> as with <tt>cspawn()</tt> with a <em>flags</em> value of CSPAWN_FLAGS_SIGBLOCKNONE; 75 a pipe is created between the child's 76 stdin (if <em>w</em> is 0) or stdout (if <em>w</em> is nonzero) and the parent. 77 The parent's end of the pipe will be stored in *<em>fd</em>. 78 </p> 79 80 <p> 81 <code> pid_t child_spawn1_socket (char const *file, char const *const *argv, char const *const *envp, int *fd) </code> <br> 82 Like <tt>child_spawn1</tt>, except that a socket, not a pipe is created between the parent 83 and the child. Both the child's stdin and stdout point to the socket; the parent has 84 its end of the socket available in *<em>fd</em>. 85 </p> 86 87 <p> 88 <code> pid_t child_spawn2 (char const *file, char const *const *argv, char const *const *envp, int *fds) </code> <br> 89 Two pipes are created between the 90 parent and the child. <em>fds</em> must point to an array of 2 ints: this 91 array is read as well as written by <tt>child_spawn2()</tt>. On function 92 call, the numbers in <em>fds</em> must describe what fds should be used 93 in the child to contain the communication pipes (for instance, if the child 94 will read from its parent on stdin and write to its parent on stdout, <em>fds</em> 95 must contain 0 and 1). On function return, <em>fds</em> contains the 96 descriptors for the pipes that read from / write to the child. 97 </p> 98 99 <p> 100 <code> pid_t child_spawn3 (char const *file, char const *const *argv, char const *const *envp, int *fds) </code> <br> 101 Three pipes are created between the 102 parent and the child. <em>fds</em> must point to an array of 3 ints: this 103 array is read as well as written by <tt>child_spawn2()</tt>. On function 104 call, the numbers in <em>fds[0]</em> and <em>fds[1]</em> must describe what fds should be used 105 in the child to read from (resp. write to) the parent. 106 On function return, <em>fds</em> contains the 107 descriptors for the pipes that read from / write to the child. <em>fds[2]</em> is 108 the reading end of a pipe; the writing end is present in the child, and its number 109 is available as the value of the <tt>SKALIBS_CHILD_SPAWN_FDS</tt> environment variable. 110 </p> 111 112 <p> 113 <code> pid_t child_spawn (char const *file, char const *const *argv, char const *const *envp, int *fds, unsigned int nfds) </code> <br> 114 More generic spawning function. <em>fds</em> must point to an array of at least <em>nfds</em> ints; 115 file descriptors reading from or writing to the child will be stored there. The function returns 116 0 on failure or the pid of the child on success. 117 </p> 118 <ul> 119 <li> If <em>nfds</em> is 0, then the function behaves like <tt>cspawn</tt> with a flags value 120 of CSPAWN_FLAGS_SIGBLOCKNONE. </li> 121 <li> If <em>nfds</em> is 1 or more, then <em>fds</em> will contain pipes between the 122 child and the parent. The parent will read on even-numbered ones 123 and write on odd-numbered ones. The child will read on <em>fds[0]</em>, write on <em>fds[1]</em>, 124 then any additional fds are available to it in the <tt>SKALIBS_CHILD_SPAWN_FDS</tt> environment 125 variable as a comma-separated list of integers. </li> 126 </ul> 127 128 <p> 129 <code> pid_t gcspawn (char const *file, char const *const *argv, char const *const *envp, uint32_t flags, cspawn_fileaction const *fa, size_t n) </code> <br> 130 Like <tt>cspawn</tt>, but <em>argv</em> will be running as a grandchild of the 131 current process. The function forks once, invokes <tt>cspawn</tt> from the child, 132 and the child exits after passing the grandchild's pid to the parent. 133 </p> 134 135 </body> 136 </html>