1posix_spawn(3C) Standard C Library Functions posix_spawn(3C)
2
6 posix_spawn, posix_spawnp - spawn a process
7
9 #include <spawn.h>
10 int posix_spawn(pid_t *restrict pid, const char *restrict path,
12 const posix_spawn_file_actions_t *file_actions,
13 const posix_spawnattr_t *restrict attrp,
14 char *const argv[restrict], char *const envp[restrict]);
15 int posix_spawnp(pid_t *restrict pid, const char *restrict file,
18 const posix_spawn_file_actions_t *file_actions,
19 const posix_spawnattr_t *restrict attrp,
20 char *const argv[restrict], char *const envp[restrict]);
21
24 The posix_spawn() and posix_spawnp() functions create a new process
25 (child process) from the specified process image. The new process image
26 is constructed from a regular executable file called the new process
27 image file.
28 When a C program is executed as the result of this call, it is entered
31 as a C language function call as follows:
32 int main(int argc, char *argv[]);
34 where argc is the argument count and argv is an array of character
38 pointers to the arguments themselves. In addition, the following vari‐
39 able
40 extern char **environ;
42 is initialized as a pointer to an array of character pointers to the
46 environment strings.
47 The argument argv is an array of character pointers to null-terminated
50 strings. The last member of this array is a null pointer and is not
51 counted in argc. These strings constitute the argument list available
52 to the new process image. The value in argv[0] should point to a file‐
53 name that is associated with the process image being started by the
54 posix_spawn() or posix_spawnp() function.
55 The argument envp is an array of character pointers to null-terminated
58 strings. These strings constitute the environment for the new process
59 image. The environment array is terminated by a null pointer.
60 The number of bytes available for the child process's combined argument
63 and environment lists is {ARG_MAX}, counting all character pointers,
64 the strings they point to, the trailing null bytes in the strings, and
65 the list-terminating null pointers. There is no additional system over‐
66 head included in this total.
67 The path argument to posix_spawn() is a pathname that identifies the
70 new process image file to execute.
71 The file parameter to posix_spawnp() is used to construct a pathname
74 that identifies the new process image file. If the file parameter con‐
75 tains a slash character, the file parameter is used as the pathname for
76 the new process image file. Otherwise, the path prefix for this file is
77 obtained by a search of the directories passed as the environment vari‐
78 able PATH. If this environment variable is not defined, the results of
79 the search are implementation-defined.
80 If file_actions is a null pointer, then file descriptors open in the
83 calling process remain open in the child process, except for those
84 whose close-on-exec flag FD_CLOEXEC is set (see fcntl(2)). For those
85 file descriptors that remain open, all attributes of the corresponding
86 open file descriptions, including file locks (see fcntl(2)), remain
87 unchanged.
88 If file_actions is not NULL, then the file descriptors open in the
91 child process are those open in the calling process as modified by the
92 spawn file actions object pointed to by file_actions and the FD_CLOEXEC
93 flag of each remaining open file descriptor after the spawn file
94 actions have been processed. The effective order of processing the
95 spawn file actions are:
96 1. The set of open file descriptors for the child process are
98 initially the same set as is open for the calling process.
99 All attributes of the corresponding open file descriptions,
100 including file locks (see fcntl(2)), remain unchanged.
101 2. The signal mask, signal default or ignore actions, and the
103 effective user and group IDs for the child process are
104 changed as specified in the attributes object referenced by
105 attrp.
106 3. The file actions specified by the spawn file actions object
108 are performed in the order in which they were added to the
109 spawn file actions object.
110 4. Any file descriptor that has its FD_CLOEXEC flag set (see
112 fcntl(2)) is closed.
113 The posix_spawnattr_t spawn attributes object type is defined in
116 <spawn.h>. It contains at least the attributes defined below.
117 If the POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute
120 of the object referenced by attrp, and the spawn-pgroup attribute of
121 the same object is non-zero, then the child's process group is as spec‐
122 ified in the spawn-pgroup attribute of the object referenced by attrp.
123 As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the
126 spawn-flags attribute of the object referenced by attrp, and the spawn-
127 pgroup attribute of the same object is set to zero, then the child will
128 be in a new process group with a process group ID equal to its process
129 ID.
130 If the POSIX_SPAWN_SETPGROUP flag is not set in the spawn-flags
133 attribute of the object referenced by attrp, the new child process
134 inherits the parent's process group.
135 If the POSIX_SPAWN_SETSCHEDPARAM flag is set in the spawn-flags
138 attribute of the object referenced by attrp, but POSIX_SPAWN_SETSCHED‐
139 ULER is not set, the new process image initially has the scheduling
140 policy of the calling process with the scheduling parameters specified
141 in the spawn-schedparam attribute of the object referenced by attrp.
142 If the POSIX_SPAWN_SETSCHEDULER flag is set in spawn-flags attribute of
145 the object referenced by attrp (regardless of the setting of the
146 POSIX_SPAWN_SETSCHEDPARAM flag), the new process image initially has
147 the scheduling policy specified in the spawn-schedpolicy attribute of
148 the object referenced by attrp and the scheduling parameters specified
149 in the spawn-schedparam attribute of the same object.
150 The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the
153 object referenced by attrp governs the effective user ID of the child
154 process. If this flag is not set, the child process inherits the parent
155 process's effective user ID. If this flag is set, the child process's
156 effective user ID is reset to the parent's real user ID. In either
157 case, if the set-user-ID mode bit of the new process image file is set,
158 the effective user ID of the child process becomes that file's owner ID
159 before the new process image begins execution. If this flag is set, the
160 child process's effective user ID is reset to the parent's real user
161 ID. In either case, if the set-user-ID mode bit of the new process
162 image file is set, the effective user ID of the child process becomes
163 that file's owner ID before the new process image begins execution.
164 The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the
167 object referenced by attrp also governs the effective group ID of the
168 child process. If this flag is not set, the child process inherits the
169 parent process's effective group ID. If this flag is set, the child
170 process's effective group ID is reset to the parent's real group ID. In
171 either case, if the set-group-ID mode bit of the new process image file
172 is set, the effective group ID of the child process becomes that file's
173 group ID before the new process image begins execution.
174 If the POSIX_SPAWN_SETSIGMASK flag is set in the spawn-flags attribute
177 of the object referenced by attrp, the child process initially has the
178 signal mask specified in the spawn-sigmask attribute of the object ref‐
179 erenced by attrp.
180 If the POSIX_SPAWN_SETSIGDEF flag is set in the spawn-flags attribute
183 of the object referenced by attrp, the signals specified in the spawn-
184 sigdefault attribute of the same object is set to their default actions
185 in the child process.
186 If the POSIX_SPAWN_SETSIGIGN_NP flag is set in the spawn-flags
189 attribute of the object referenced by attrp, the signals specified in
190 the spawn-sigignore attribute of the same object are set to be ignored
191 in the child process.
192 If both POSIX_SPAWN_SETSIGDEF and POSIX_SPAWN_SETSIGIGN_NP flags are
195 set in the spawn-flags attribute of the object referenced by attrp, the
196 actions for POSIX_SPAWN_SETSIGDEF take precedence over the actions for
197 POSIX_SPAWN_SETSIGIGN_NP.
198 If the POSIX_SPAWN_NOSIGCHLD_NP flag is set in the spawn-flags
201 attribute of the object referenced by attrp, no SIGCHLD signal will be
202 posted to the parent process when the child process terminates, regard‐
203 less of the disposition of the SIGCHLD signal in the parent. SIGCHLD
204 signals are still possible for job control stop and continue actions if
205 the parent has requested them.
206 If the POSIX_SPAWN_WAITPID_NP flag is set in the spawn-flags attribute
209 of the object referenced by attrp, no wait-for-multiple-pids operation
210 by the parent, as in wait(), waitid(P_ALL), or waitid(P_PGID), will
211 succeed in reaping the child, and the child will not be reaped automat‐
212 ically due the disposition of the SIGCHLD signal being set to be
213 ignored in the parent. Only a specific wait for the child, as in
214 waitid(P_PID, pid), is allowed and it is required, else when the child
215 exits it will remain a zombie until the parent exits.
216 If the POSIX_SPAWN_NOEXECERR_NP flag is set in the spawn-flags
219 attribute of the object referenced by attrp, and if the specified
220 process image file cannot be executed, then the posix_spawn() and
221 posix_spawnp() functions do not fail with one of the exec(2) error
222 codes, as is normal, but rather return successfully having created a
223 child process that exits immediately with exit status 127. This flag
224 permits system(3C) and popen(3C) to be implemented with posix_spawn()
225 and still conform strictly to their POSIX specifications.
226 Signals set to be caught or set to the default action in the calling
229 process are set to the default action in the child process, unless the
230 POSIX_SPAWN_SETSIGIGN_NP flag is set in the spawn-flags attribute of
231 the object referenced by attrp and the signals are specified in the
232 spawn-sigignore attribute of the same object.
233 Except for SIGCHLD, signals set to be ignored by the calling process
236 image are set to be ignored by the child process, unless otherwise
237 specified by the POSIX_SPAWN_SETSIGDEF flag being set in the spawn-
238 flags attribute of the object referenced by attrp and the signals being
239 indicated in the spawn-sigdefault attribute of the object referenced by
240 attrp.
241 If the SIGCHLD signal is set to be ignored by the calling process, it
244 is unspecified whether the SIGCHLD signal is set to be ignored or to
245 the default action in the child process, unless otherwise specified by
246 the POSIX_SPAWN_SETSIGDEF flag being set in the spawn-flags attribute
247 of the object referenced by attrp and the SIGCHLD signal being indi‐
248 cated in the spawn-sigdefault attribute of the object referenced by
249 attrp.
250 If the value of the attrp pointer is NULL, then the default values are
253 used.
254 All process attributes, other than those influenced by the attributes
257 set in the object referenced by attrp as specified above or by the file
258 descriptor manipulations specified in file_actions appear in the new
259 process image as though fork() had been called to create a child
260 process and then a member of the exec family of functions had been
261 called by the child process to execute the new process image.
262 The fork handlers are not run when posix_spawn() or posix_spawnp() is
265 called.
266
268 Upon successful completion, posix_spawn() and posix_spawnp() return the
269 process ID of the child process to the parent process in the variable
270 pointed to by a non-null pid argument, and return zero as the function
271 return value. Otherwise, no child process is created, the value stored
272 into the variable pointed to by a non-null pid is unspecified, and an
273 error number is returned as the function return value to indicate the
274 error. If the pid argument is a null pointer, the process ID of the
275 child is not returned to the caller.
276
278 The posix_spawn() and posix_spawnp() functions will fail if:
279 EINVAL The value specified by file_actions or attrp is invalid.
281 If posix_spawn() or posix_spawnp() fails for any of the reasons that
285 would cause fork() or one of the exec family of functions to fail, an
286 error value is returned as described by fork(2) and exec(2), respec‐
287 tively
288 If POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute of the
291 object referenced by attrp, and posix_spawn() or posix_spawnp() fails
292 while changing the child's process group, an error value is returned as
293 described by setpgid(2).
294 If POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not
297 set in the spawn-flags attribute of the object referenced by attrp,
298 then if posix_spawn() or posix_spawnp() fails for any of the reasons
299 that would cause sched_setparam() to fail, an error value is returned
300 as described by sched_setparam(3C).
301 If POSIX_SPAWN_SETSCHEDULER is set in the spawn-flags attribute of the
304 object referenced by attrp, and if posix_spawn() or posix_spawnp()
305 fails for any of the reasons that would cause sched_setscheduler() to
306 fail, an error value is returned as described by sched_setsched‐
307 uler(3C).
308 If the file_actions argument is not NULL and specifies any close(),
311 dup2(), or open() actions to be performed, and if posix_spawn() or
312 posix_spawnp() fails for any of the reasons that would cause close(),
313 dup2(), or open() to fail, an error value is returned as described by
314 close(2), dup2(3C), or open(2), respectively. An open file action
315 might, by itself, result in any of the errors described by close() or
316 dup2(), in addition to those described by open().
317 If a close(2) operation is specified to be performed for a file
320 descriptor that is not open at the time of the call to posix_spawn() or
321 posix_spawnp(), the action does not cause posix_spawn() or
322 posix_spawnp() to fail.
323
325 See attributes(5) for descriptions of the following attributes:
326 ┌─────────────────────────────┬─────────────────────────────┐
331 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
332 ├─────────────────────────────┼─────────────────────────────┤
333 │Interface Stability │Committed │
334 ├─────────────────────────────┼─────────────────────────────┤
335 │MT-Level │MT-Safe │
336 ├─────────────────────────────┼─────────────────────────────┤
337 │Standard │See standards(5). │
338 └─────────────────────────────┴─────────────────────────────┘
339
341 alarm(2), chmod(2), close(2), dup(2), exec(2), exit(2), fcntl(2),
342 fork(2), kill(2), open(2), setpgid(2), setuid(2), stat(2), times(2),
343 dup2(3C), popen(3C), posix_spawn_file_actions_addclose(3C),
344 posix_spawn_file_actions_adddup2(3C),
345 posix_spawn_file_actions_addopen(3C),
346 posix_spawn_file_actions_destroy(3C),
347 posix_spawn_file_actions_init(3C), posix_spawnattr_destroy(3C),
348 posix_spawnattr_getflags(3C), posix_spawnattr_getpgroup(3C),
349 posix_spawnattr_getschedparam(3C), posix_spawnattr_getschedpolicy(3C),
350 posix_spawnattr_getsigdefault(3C), posix_spawnattr_getsigignore_np(3C),
351 posix_spawnattr_getsigmask(3C), posix_spawnattr_init(3C), posix_spaw‐
352 nattr_setflags(3C), posix_spawnattr_setpgroup(3C), posix_spaw‐
353 nattr_setschedparam(3C), posix_spawnattr_setschedpolicy(3C),
354 posix_spawnattr_setsigdefault(3C), posix_spawnattr_setsigignore_np(3C),
355 posix_spawnattr_setsigmask(3C), sched_setparam(3C), sched_setsched‐
356 uler(3C), system(3C), wait(3C), attributes(5), standards(5)
357
359 The SUSv3 POSIX standard (The Open Group Base Specifications Issue 6,
360 IEEE Std 1003.1-2001) permits the posix_spawn() and posix_spawnp()
361 functions to return successfully before some of the above-described
362 errors are detected, allowing the child process to fail instead:
363 ... if the error occurs after the calling process
365 successfully returns, the child process exits with
366 exit status 127.
367 With the one exception of when the POSIX_SPAWN_NOEXECERR_NP flag is
371 passed in the attributes structure, this behavior is not present in the
372 Solaris implementation. Any error that occurs before the new process
373 image is successfully constructed causes the posix_spawn() and
374 posix_spawnp() functions to return the corresponding non-zero error
375 value without creating a child process.
376 The POSIX_SPAWN_NOSIGCHLD_NP, POSIX_SPAWN_WAITPID_NP, POSIX_SPAWN_NOEX‐
379 ECERR_NP, and POSIX_SPAWN_SETSIGIGN_NP flags and the posix_spaw‐
380 nattr_getsigignore_np() and posix_spawnattr_setsigignore_np() functions
381 are non-portable Solaris extensions to the posix_spawn() and
382 posix_spawnp() interfaces.
383SunOS 5.11 20 Feb 2009 posix_spawn(3C)