1 .\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" Portions of this text are reprinted and reproduced in electronic form
26 .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
27 .\" Portable Operating System Interface (POSIX), The Open Group Base
28 .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
29 .\" Electrical and Electronics Engineers, Inc and The Open Group. In the
30 .\" event of any discrepancy between this version and the original IEEE and
31 .\" The Open Group Standard, the original IEEE and The Open Group Standard is
32 .\" the referee document. The original Standard can be obtained online at
33 .\" http://www.opengroup.org/unix/online.html.
49 .Fn posix_spawn "pid_t *restrict pid" "const char *restrict path" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]"
51 .Fn posix_spawnp "pid_t *restrict pid" "const char *restrict file" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]"
57 functions create a new process (child process) from the specified
59 The new process image is constructed from a regular executable
60 file called the new process image file.
62 When a C program is executed as the result of this call, it is
63 entered as a C-language function call as follows:
64 .Bd -literal -offset indent
65 int main(int argc, char *argv[]);
70 is the argument count and
72 is an array of character pointers to the arguments themselves.
73 In addition, the variable:
74 .Bd -literal -offset indent
75 extern char **environ;
78 points to an array of character pointers to
79 the environment strings.
83 is an array of character pointers to null-terminated
85 The last member of this array is a null pointer and is not counted
88 These strings constitute the argument list available to the new process
93 a filename that is associated with the process image being started by
102 is an array of character pointers to null-terminated strings.
103 These strings constitute the environment for the new process image.
104 The environment array is terminated by a null pointer.
110 is a pathname that identifies the new process image file to execute.
116 is used to construct a pathname that identifies the new process
118 If the file parameter contains a slash character, the file parameter
119 is used as the pathname for the new process image file.
120 Otherwise, the path prefix for this file is obtained by a search
121 of the directories passed as the environment variable
123 If this variable is not specified,
124 the default path is set according to the
129 .Dq Ev /usr/bin:/bin .
133 is a null pointer, then file descriptors open in the
134 calling process remain open in the child process, except for those
135 whose close-on-exec flag
140 file descriptors that remain open, all attributes of the corresponding
141 open file descriptions, including file locks (see
147 is not NULL, then the file descriptors open in the child process are
148 those open in the calling process as modified by the spawn file
149 actions object pointed to by
153 flag of each remaining open file descriptor after the spawn file actions
155 The effective order of processing the spawn file actions are:
158 The set of open file descriptors for the child process initially
159 are the same set as is open for the calling process.
160 All attributes of the corresponding open file descriptions, including
165 The signal mask, signal default actions, and the effective user and
166 group IDs for the child process are changed as specified in the
167 attributes object referenced by
170 The file actions specified by the spawn file actions object are
171 performed in the order in which they were added to the spawn file
174 Any file descriptor that has its
182 .Vt posix_spawnattr_t
183 spawn attributes object type is defined in
185 It contains the attributes defined below.
188 .Dv POSIX_SPAWN_SETPGROUP
189 flag is set in the spawn-flags attribute of the object referenced by
191 and the spawn-pgroup attribute of the same object is non-zero, then the
192 child's process group is as specified in the spawn-pgroup
193 attribute of the object referenced by
196 As a special case, if the
197 .Dv POSIX_SPAWN_SETPGROUP
198 flag is set in the spawn-flags attribute of the object referenced by
200 and the spawn-pgroup attribute of the same object is set to zero, then
201 the child is in a new process group with a process group ID equal
205 .Dv POSIX_SPAWN_SETPGROUP
206 flag is not set in the spawn-flags attribute of the object referenced by
208 the new child process inherits the parent's process group.
211 .Dv POSIX_SPAWN_SETSCHEDPARAM
212 flag is set in the spawn-flags attribute of the object referenced by
215 .Dv POSIX_SPAWN_SETSCHEDULER
216 is not set, the new process image initially has the scheduling
217 policy of the calling process with the scheduling parameters specified
218 in the spawn-schedparam attribute of the object referenced by
222 .Dv POSIX_SPAWN_SETSCHEDULER
223 flag is set in the spawn-flags attribute of the object referenced by
225 (regardless of the setting of the
226 .Dv POSIX_SPAWN_SETSCHEDPARAM
227 flag), the new process image initially has the scheduling policy
228 specified in the spawn-schedpolicy attribute of the object referenced by
230 and the scheduling parameters specified in the spawn-schedparam
231 attribute of the same object.
234 .Dv POSIX_SPAWN_RESETIDS
235 flag in the spawn-flags attribute of the object referenced by
237 governs the effective user ID of the child process.
238 If this flag is not set, the child process inherits the parent
239 process' effective user ID.
240 If this flag is set, the child process' effective user ID is reset
241 to the parent's real user ID.
242 In either case, if the set-user-ID mode bit of the new process image
243 file is set, the effective user ID of the child process becomes
244 that file's owner ID before the new process image begins execution.
247 .Dv POSIX_SPAWN_RESETIDS
248 flag in the spawn-flags attribute of the object referenced by
250 also governs the effective group ID of the child process.
251 If this flag is not set, the child process inherits the parent
252 process' effective group ID.
253 If this flag is set, the child process' effective group ID is
254 reset to the parent's real group ID.
255 In either case, if the set-group-ID mode bit of the new process image
256 file is set, the effective group ID of the child process becomes
257 that file's group ID before the new process image begins execution.
260 .Dv POSIX_SPAWN_SETSIGMASK
261 flag is set in the spawn-flags attribute of the object referenced by
263 the child process initially has the signal mask specified in the
264 spawn-sigmask attribute of the object referenced by
268 .Dv POSIX_SPAWN_SETSIGDEF
269 flag is set in the spawn-flags attribute of the object referenced by
271 the signals specified in the spawn-sigdefault attribute of the same
272 object is set to their default actions in the child process.
273 Signals set to the default action in the parent process is set to
274 the default action in the child process.
276 Signals set to be caught by the calling process is set to the
277 default action in the child process.
279 Signals set to be ignored by the calling process image is set to
280 be ignored by the child process, unless otherwise specified by the
281 .Dv POSIX_SPAWN_SETSIGDEF
282 flag being set in the spawn-flags attribute of the object referenced by
284 and the signals being indicated in the spawn-sigdefault attribute
285 of the object referenced by
290 pointer is NULL, then the default values are used.
292 All process attributes, other than those influenced by the attributes
293 set in the object referenced by
295 as specified above or by the file descriptor manipulations specified in
297 appear in the new process image as though
299 had been called to create a child process and then
301 had been called by the child process to execute the new process image.
303 The implementation uses vfork(), thus the fork handlers are not run when
309 Upon successful completion,
313 return the process ID of the child process to the parent process,
314 in the variable pointed to by a non-NULL
316 argument, and return zero as the function return value.
317 Otherwise, no child process is created, no value is stored into
318 the variable pointed to by
320 and an error number is returned as the function return value to
324 argument is a null pointer, the process ID of the child is not returned
333 fail for any of the reasons that would cause
337 to fail, an error value is returned as described by
341 respectively (or, if the error occurs after the calling process successfully
342 returns, the child process exits with exit status 127).
345 .Nm POSIX_SPAWN_SETPGROUP
346 is set in the spawn-flags attribute of the object referenced by attrp, and
350 fails while changing the child's process group, an error value is returned as
353 (or, if the error occurs after the calling process successfully returns,
354 the child process exits with exit status 127).
357 .Nm POSIX_SPAWN_SETSCHEDPARAM
359 .Nm POSIX_SPAWN_SETSCHEDULER
360 is not set in the spawn-flags attribute of the object referenced by attrp, then
365 fails for any of the reasons that would cause
367 to fail, an error value is returned as described by
369 (or, if the error occurs after the calling process successfully returns, the
370 child process exits with exit status 127).
373 .Nm POSIX_SPAWN_SETSCHEDULER
374 is set in the spawn-flags attribute of the object referenced by attrp, and if
378 fails for any of the reasons that would cause
379 .Fn sched_setscheduler
380 to fail, an error value is returned as described by
381 .Fn sched_setscheduler
382 (or, if the error occurs after the calling process successfully returns,
383 the child process exits with exit status 127).
387 argument is not NULL, and specifies any dup2 or open actions to be
392 fails for any of the reasons that would cause
396 to fail, an error value is returned as described by
400 respectively (or, if the error occurs after the calling process successfully
401 returns, the child process exits with exit status 127). An open file action
402 may, by itself, result in any of the errors described by
404 in addition to those described by
406 This implementation ignores any errors from
408 including trying to close a descriptor that is not open.
416 .Xr posix_spawn_file_actions_addclose 3 ,
417 .Xr posix_spawn_file_actions_adddup2 3 ,
418 .Xr posix_spawn_file_actions_addopen 3 ,
419 .Xr posix_spawn_file_actions_destroy 3 ,
420 .Xr posix_spawn_file_actions_init 3 ,
421 .Xr posix_spawnattr_destroy 3 ,
422 .Xr posix_spawnattr_getflags 3 ,
423 .Xr posix_spawnattr_getpgroup 3 ,
424 .Xr posix_spawnattr_getschedparam 3 ,
425 .Xr posix_spawnattr_getschedpolicy 3 ,
426 .Xr posix_spawnattr_getsigdefault 3 ,
427 .Xr posix_spawnattr_getsigmask 3 ,
428 .Xr posix_spawnattr_init 3 ,
429 .Xr posix_spawnattr_setflags 3 ,
430 .Xr posix_spawnattr_setpgroup 3 ,
431 .Xr posix_spawnattr_setschedparam 3 ,
432 .Xr posix_spawnattr_setschedpolicy 3 ,
433 .Xr posix_spawnattr_setsigdefault 3 ,
434 .Xr posix_spawnattr_setsigmask 3 ,
435 .Xr sched_setparam 2 ,
436 .Xr sched_setscheduler 2 ,
446 except that they ignore all errors from
448 A future update of the Standard is expected to require that these functions
449 not fail because a file descriptor to be closed (via
450 .Fn posix_spawn_file_actions_addclose )
457 functions first appeared in
460 .An Ed Schouten Aq Mt ed@FreeBSD.org