| blob | d0384d7c6c17c1efcc519ef046f41d287798ed29 |
1 .\" $NetBSD: posix_spawn.3,v 1.4 2013/07/20 21:39:57 wiz Exp $
2 .\"
3 .\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" SUCH DAMAGE.
26 .\"
27 .\" Portions of this text are reprinted and reproduced in electronic form
28 .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
29 .\" Portable Operating System Interface (POSIX), The Open Group Base
30 .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
31 .\" Electrical and Electronics Engineers, Inc and The Open Group. In the
32 .\" event of any discrepancy between this version and the original IEEE and
33 .\" The Open Group Standard, the original IEEE and The Open Group Standard is
34 .\" the referee document. The original Standard can be obtained online at
35 .\" http://www.opengroup.org/unix/online.html.
36 .\"
37 .\" $FreeBSD: src/lib/libc/gen/posix_spawn.3,v 1.2.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $
38 .\"
39 .Dd December 20, 2011
40 .Dt POSIX_SPAWN 3
41 .Os
42 .Sh NAME
43 .Nm posix_spawn ,
44 .Nm posix_spawnp
45 .Nd "spawn a process"
46 .Sh LIBRARY
47 .Lb libc
48 .Sh SYNOPSIS
49 .In spawn.h
50 .Ft int
51 .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]"
52 .Ft int
53 .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]"
54 .Sh DESCRIPTION
55 The
56 .Fn posix_spawn
57 and
58 .Fn posix_spawnp
59 functions create a new process (child process) from the specified
60 process image.
61 The new process image is constructed from a regular executable
62 file called the new process image file.
63 .Pp
64 When a C program is executed as the result of this call, it is
65 entered as a C-language function call as follows:
66 .Bd -literal -offset indent
67 int main(int argc, char *argv[]);
68 .Ed
69 .Pp
70 where
71 .Fa argc
72 is the argument count and
73 .Fa argv
74 is an array of character pointers to the arguments themselves.
75 In addition, the variable:
76 .Bd -literal -offset indent
77 extern char **environ;
78 .Ed
79 .Pp
80 points to an array of character pointers to
81 the environment strings.
82 .Pp
83 The argument
84 .Fa argv
85 is an array of character pointers to null-terminated
86 strings.
87 The last member of this array is a null pointer and is not counted
88 in
89 .Fa argc .
90 These strings constitute the argument list available to the new process
91 image.
92 The value in
93 .Fa argv Ns [0]
94 should point to
95 a filename that is associated with the process image being started by
96 the
97 .Fn posix_spawn
98 or
99 .Fn posix_spawnp
100 function.
101 .Pp
102 The argument
103 .Fa envp
104 is an array of character pointers to null-terminated strings.
105 These strings constitute the environment for the new process image.
106 The environment array is terminated by a null pointer.
107 .Pp
108 The
109 .Fa path
110 argument to
111 .Fn posix_spawn
112 is a pathname that identifies the new process image file to execute.
113 .Pp
114 The
115 .Fa file
116 parameter to
117 .Fn posix_spawnp
118 is used to construct a pathname that identifies the new process
119 image file.
120 If the file parameter contains a slash character, the file parameter
121 is used as the pathname for the new process image file.
122 Otherwise, the path prefix for this file is obtained by a search
123 of the directories passed as the environment variable
124 .Dq Ev PATH .
125 If this variable is not specified,
126 the default path is set according to the
127 .Dv _PATH_DEFPATH
128 definition in
129 .In paths.h ,
130 which is set to
131 .Dq Ev /usr/bin:/bin .
132 .Pp
133 If
134 .Fa file_actions
135 is a null pointer, then file descriptors open in the
136 calling process remain open in the child process, except for those
137 whose close-on-exec flag
138 .Dv FD_CLOEXEC
139 is set (see
140 .Fn fcntl ) .
141 For those
142 file descriptors that remain open, all attributes of the corresponding
143 open file descriptions, including file locks (see
144 .Fn fcntl ) ,
145 remain unchanged.
146 .Pp
147 If
148 .Fa file_actions
149 is not
150 .Dv NULL ,
151 then the file descriptors open in the child process are
152 those open in the calling process as modified by the spawn file
153 actions object pointed to by
154 .Fa file_actions
155 and the
156 .Dv FD_CLOEXEC
157 flag of each remaining open file descriptor after the spawn file actions
158 have been processed.
159 The effective order of processing the spawn file actions are:
160 .Bl -enum
161 .It
162 The set of open file descriptors for the child process initially
163 are the same set as is open for the calling process.
164 All attributes of the corresponding open file descriptions, including
165 file locks (see
166 .Fn fcntl ) ,
167 remain unchanged.
168 .It
169 The signal mask, signal default actions, and the effective user and
170 group IDs for the child process are changed as specified in the
171 attributes object referenced by
172 .Fa attrp .
173 .It
174 The file actions specified by the spawn file actions object are
175 performed in the order in which they were added to the spawn file
176 actions object.
177 .It
178 Any file descriptor that has its
179 .Dv FD_CLOEXEC
180 flag set (see
181 .Fn fcntl )
182 is closed.
183 .El
184 .Pp
185 The
186 .Vt posix_spawnattr_t
187 spawn attributes object type is defined in
188 .In spawn.h .
189 It contains the attributes defined below.
190 .Pp
191 If the
192 .Dv POSIX_SPAWN_SETPGROUP
193 flag is set in the spawn-flags attribute of the object referenced by
194 .Fa attrp ,
195 and the spawn-pgroup attribute of the same object is non-zero, then the
196 child's process group is as specified in the spawn-pgroup
197 attribute of the object referenced by
198 .Fa attrp .
199 .Pp
200 As a special case, if the
201 .Dv POSIX_SPAWN_SETPGROUP
202 flag is set in the spawn-flags attribute of the object referenced by
203 .Fa attrp ,
204 and the spawn-pgroup attribute of the same object is set to zero, then
205 the child is in a new process group with a process group ID equal
206 to its process ID.
207 .Pp
208 If the
209 .Dv POSIX_SPAWN_SETPGROUP
210 flag is not set in the spawn-flags attribute of the object referenced by
211 .Fa attrp ,
212 the new child process inherits the parent's process group.
213 .Pp
214 If the
215 .Dv POSIX_SPAWN_SETSCHEDPARAM
216 flag is set in the spawn-flags attribute of the object referenced by
217 .Fa attrp ,
218 but
219 .Dv POSIX_SPAWN_SETSCHEDULER
220 is not set, the new process image initially has the scheduling
221 policy of the calling process with the scheduling parameters specified
222 in the spawn-schedparam attribute of the object referenced by
223 .Fa attrp .
224 .Pp
225 If the
226 .Dv POSIX_SPAWN_SETSCHEDULER
227 flag is set in the spawn-flags attribute of the object referenced by
228 .Fa attrp
229 (regardless of the setting of the
230 .Dv POSIX_SPAWN_SETSCHEDPARAM
231 flag), the new process image initially has the scheduling policy
232 specified in the spawn-schedpolicy attribute of the object referenced by
233 .Fa attrp
234 and the scheduling parameters specified in the spawn-schedparam
235 attribute of the same object.
236 .Pp
237 The
238 .Dv POSIX_SPAWN_RESETIDS
239 flag in the spawn-flags attribute of the object referenced by
240 .Fa attrp
241 governs the effective user ID of the child process.
242 If this flag is not set, the child process inherits the parent
243 process' effective user ID.
244 If this flag is set, the child process' effective user ID is reset
245 to the parent's real user ID.
246 In either case, if the set-user-ID mode bit of the new process image
247 file is set, the effective user ID of the child process becomes
248 that file's owner ID before the new process image begins execution.
249 .Pp
250 The
251 .Dv POSIX_SPAWN_RESETIDS
252 flag in the spawn-flags attribute of the object referenced by
253 .Fa attrp
254 also governs the effective group ID of the child process.
255 If this flag is not set, the child process inherits the parent
256 process' effective group ID.
257 If this flag is set, the child process' effective group ID is
258 reset to the parent's real group ID.
259 In either case, if the set-group-ID mode bit of the new process image
260 file is set, the effective group ID of the child process becomes
261 that file's group ID before the new process image begins execution.
262 .Pp
263 If the
264 .Dv POSIX_SPAWN_SETSIGMASK
265 flag is set in the spawn-flags attribute of the object referenced by
266 .Fa attrp ,
267 the child process initially has the signal mask specified in the
268 spawn-sigmask attribute of the object referenced by
269 .Fa attrp .
270 .Pp
271 If the
272 .Dv POSIX_SPAWN_SETSIGDEF
273 flag is set in the spawn-flags attribute of the object referenced by
274 .Fa attrp ,
275 the signals specified in the spawn-sigdefault attribute of the same
276 object is set to their default actions in the child process.
277 Signals set to the default action in the parent process is set to
278 the default action in the child process.
279 .Pp
280 Signals set to be caught by the calling process is set to the
281 default action in the child process.
282 .Pp
283 Signals set to be ignored by the calling process image is set to
284 be ignored by the child process, unless otherwise specified by the
285 .Dv POSIX_SPAWN_SETSIGDEF
286 flag being set in the spawn-flags attribute of the object referenced by
287 .Fa attrp
288 and the signals being indicated in the spawn-sigdefault attribute
289 of the object referenced by
290 .Fa attrp .
291 .Pp
292 If the value of the
293 .Fa attrp
294 pointer is
295 .Dv NULL ,
296 then the default values are used.
297 .Pp
298 All process attributes, other than those influenced by the attributes
299 set in the object referenced by
300 .Fa attrp
301 as specified above or by the file descriptor manipulations specified in
302 .Fa file_actions ,
303 appear in the new process image as though
304 .Fn vfork
305 had been called to create a child process and then
306 .Fn execve
307 had been called by the child process to execute the new process image.
308 .Pp
309 The implementation uses vfork(), thus the fork handlers are not run when
310 .Fn posix_spawn
311 or
312 .Fn posix_spawnp
313 is called.
314 .Sh RETURN VALUES
315 Upon successful completion,
316 .Fn posix_spawn
317 and
318 .Fn posix_spawnp
319 return the process ID of the child process to the parent process,
320 in the variable pointed to by a
321 .Pf non- Dv NULL
322 .Fa pid
323 argument, and return zero as the function return value.
324 Otherwise, no child process is created, no value is stored into
325 the variable pointed to by
326 .Fa pid ,
327 and an error number is returned as the function return value to
328 indicate the error.
329 If the
330 .Fa pid
331 argument is a null pointer, the process ID of the child is not returned
332 to the caller.
333 .Sh ERRORS
334 .Bl -enum
335 .It
336 If
337 .Fn posix_spawn
338 and
339 .Fn posix_spawnp
340 fail for any of the reasons that would cause
341 .Fn vfork
342 or one of the
343 .Nm exec
344 to fail, an error value is returned as described by
345 .Fn vfork
346 and
347 .Nm exec ,
348 respectively (or, if the error occurs after the calling process successfully
349 returns, the child process exits with exit status 127).
350 .It
351 If
352 .Nm POSIX_SPAWN_SETPGROUP
353 is set in the spawn-flags attribute of the object referenced by attrp, and
354 .Fn posix_spawn
355 or
356 .Fn posix_spawnp
357 fails while changing the child's process group, an error value is returned as
358 described by
359 .Fn setpgid
360 (or, if the error occurs after the calling process successfully returns,
361 the child process exits with exit status 127).
362 .It
363 If
364 .Nm POSIX_SPAWN_SETSCHEDPARAM
365 is set and
366 .Nm POSIX_SPAWN_SETSCHEDULER
367 is not set in the spawn-flags attribute of the object referenced by attrp, then
368 if
369 .Fn posix_spawn
370 or
371 .Fn posix_spawnp
372 fails for any of the reasons that would cause
373 .Fn sched_setparam
374 to fail, an error value is returned as described by
375 .Fn sched_setparam
376 (or, if the error occurs after the calling process successfully returns, the
377 child process exits with exit status 127).
378 .It
379 If
380 .Nm POSIX_SPAWN_SETSCHEDULER
381 is set in the spawn-flags attribute of the object referenced by attrp, and if
382 .Fn posix_spawn
383 or
384 .Fn posix_spawnp
385 fails for any of the reasons that would cause
386 .Fn sched_setscheduler
387 to fail, an error value is returned as described by
388 .Fn sched_setscheduler
389 (or, if the error occurs after the calling process successfully returns,
390 the child process exits with exit status 127).
391 .It
392 If the
393 .Fa file_actions
394 argument is not
395 .Dv NULL ,
396 and specifies any
397 .Fn close ,
398 .Fn dup2 ,
399 or
400 .Fn open
401 actions to be performed, and if
402 .Fn posix_spawn
403 or
404 .Fn posix_spawnp
405 fails for any of the reasons that would cause
406 .Fn close ,
407 .Fn dup2 ,
408 or
409 .Fn open
410 to fail, an error value is returned as described by
411 .Fn close ,
412 .Fn dup2 ,
413 and
414 .Fn open ,
415 respectively (or, if the error occurs after the calling process successfully
416 returns, the child process exits with exit status 127). An open file action
417 may, by itself, result in any of the errors described by
418 .Fn close
419 or
420 .Fn dup2 ,
421 in addition to those described by
422 .Fn open .
423 .El
424 .Sh SEE ALSO
425 .Xr close 2 ,
426 .Xr dup2 2 ,
427 .Xr execve 2 ,
428 .Xr fcntl 2 ,
429 .Xr open 2 ,
430 .Xr setpgid 2 ,
431 .Xr vfork 2 ,
432 .Xr posix_spawn_file_actions_addclose 3 ,
433 .Xr posix_spawn_file_actions_adddup2 3 ,
434 .Xr posix_spawn_file_actions_addopen 3 ,
435 .Xr posix_spawn_file_actions_destroy 3 ,
436 .Xr posix_spawn_file_actions_init 3 ,
437 .Xr posix_spawnattr_destroy 3 ,
438 .Xr posix_spawnattr_getflags 3 ,
439 .Xr posix_spawnattr_getpgroup 3 ,
440 .Xr posix_spawnattr_getschedparam 3 ,
441 .Xr posix_spawnattr_getschedpolicy 3 ,
442 .Xr posix_spawnattr_getsigdefault 3 ,
443 .Xr posix_spawnattr_getsigmask 3 ,
444 .Xr posix_spawnattr_init 3 ,
445 .Xr posix_spawnattr_setflags 3 ,
446 .Xr posix_spawnattr_setpgroup 3 ,
447 .Xr posix_spawnattr_setschedparam 3 ,
448 .Xr posix_spawnattr_setschedpolicy 3 ,
449 .Xr posix_spawnattr_setsigdefault 3 ,
450 .Xr posix_spawnattr_setsigmask 3 ,
451 .Xr sched_setparam 3 ,
452 .Xr sched_setscheduler 3
453 .Sh STANDARDS
454 The
455 .Fn posix_spawn
456 and
457 .Fn posix_spawnp
458 functions conform to
459 .St -p1003.1-2001 .
460 .Sh HISTORY
461 The
462 .Fn posix_spawn
463 and
464 .Fn posix_spawnp
465 functions first appeared in
466 .Fx 8.0 .
467 The library parts were ported and a kernel implementation of
468 .Fn posix_spawn
469 added for
470 .Nx 6.0
471 during Google Summer of Code by Charles Zhang and Martin Husemann.
472 .Sh AUTHORS
473 .An Ed Schouten Aq Mt ed@FreeBSD.org