1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
<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, uint16_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>
<p>
<code> pid_t gcspawn (char const *file, char const *const *argv, char const *const *envp, uint16_t flags, cspawn_fileaction const *fa, size_t n) </code> <br>
Like <tt>cspawn</tt>, but <em>argv</em> will be running as a grandchild of the
current process. The function forks once, invokes <tt>cspawn</tt> from the child,
and the child exits after passing the grandchild's pid to the parent.
</p>
</body>
</html>
|
