| blob | 67f5bb408bdfd7b2b723cfeb6347904ccfc86f14 |
1 .\" $NetBSD: posix_spawn.3,v 1.6 2014/02/02 16:59:06 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 February 2, 2014
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 maximum number of
186 .Fa file_actions
187 objects is limited to the
188 .Dv RLIMIT_NOFILE
189 rlimit times 2.
190 .Pp
191 The
192 .Vt posix_spawnattr_t
193 spawn attributes object type is defined in
194 .In spawn.h .
195 It contains the attributes defined below.
196 .Pp
197 If the
198 .Dv POSIX_SPAWN_SETPGROUP
199 flag is set in the spawn-flags attribute of the object referenced by
200 .Fa attrp ,
201 and the spawn-pgroup attribute of the same object is non-zero, then the
202 child's process group is as specified in the spawn-pgroup
203 attribute of the object referenced by
204 .Fa attrp .
205 .Pp
206 As a special case, if the
207 .Dv POSIX_SPAWN_SETPGROUP
208 flag is set in the spawn-flags attribute of the object referenced by
209 .Fa attrp ,
210 and the spawn-pgroup attribute of the same object is set to zero, then
211 the child is in a new process group with a process group ID equal
212 to its process ID.
213 .Pp
214 If the
215 .Dv POSIX_SPAWN_SETPGROUP
216 flag is not set in the spawn-flags attribute of the object referenced by
217 .Fa attrp ,
218 the new child process inherits the parent's process group.
219 .Pp
220 If the
221 .Dv POSIX_SPAWN_SETSCHEDPARAM
222 flag is set in the spawn-flags attribute of the object referenced by
223 .Fa attrp ,
224 but
225 .Dv POSIX_SPAWN_SETSCHEDULER
226 is not set, the new process image initially has the scheduling
227 policy of the calling process with the scheduling parameters specified
228 in the spawn-schedparam attribute of the object referenced by
229 .Fa attrp .
230 .Pp
231 If the
232 .Dv POSIX_SPAWN_SETSCHEDULER
233 flag is set in the spawn-flags attribute of the object referenced by
234 .Fa attrp
235 (regardless of the setting of the
236 .Dv POSIX_SPAWN_SETSCHEDPARAM
237 flag), the new process image initially has the scheduling policy
238 specified in the spawn-schedpolicy attribute of the object referenced by
239 .Fa attrp
240 and the scheduling parameters specified in the spawn-schedparam
241 attribute of the same object.
242 .Pp
243 The
244 .Dv POSIX_SPAWN_RESETIDS
245 flag in the spawn-flags attribute of the object referenced by
246 .Fa attrp
247 governs the effective user ID of the child process.
248 If this flag is not set, the child process inherits the parent
249 process' effective user ID.
250 If this flag is set, the child process' effective user ID is reset
251 to the parent's real user ID.
252 In either case, if the set-user-ID mode bit of the new process image
253 file is set, the effective user ID of the child process becomes
254 that file's owner ID before the new process image begins execution.
255 .Pp
256 The
257 .Dv POSIX_SPAWN_RESETIDS
258 flag in the spawn-flags attribute of the object referenced by
259 .Fa attrp
260 also governs the effective group ID of the child process.
261 If this flag is not set, the child process inherits the parent
262 process' effective group ID.
263 If this flag is set, the child process' effective group ID is
264 reset to the parent's real group ID.
265 In either case, if the set-group-ID mode bit of the new process image
266 file is set, the effective group ID of the child process becomes
267 that file's group ID before the new process image begins execution.
268 .Pp
269 If the
270 .Dv POSIX_SPAWN_SETSIGMASK
271 flag is set in the spawn-flags attribute of the object referenced by
272 .Fa attrp ,
273 the child process initially has the signal mask specified in the
274 spawn-sigmask attribute of the object referenced by
275 .Fa attrp .
276 .Pp
277 If the
278 .Dv POSIX_SPAWN_SETSIGDEF
279 flag is set in the spawn-flags attribute of the object referenced by
280 .Fa attrp ,
281 the signals specified in the spawn-sigdefault attribute of the same
282 object is set to their default actions in the child process.
283 Signals set to the default action in the parent process is set to
284 the default action in the child process.
285 .Pp
286 Signals set to be caught by the calling process is set to the
287 default action in the child process.
288 .Pp
289 Signals set to be ignored by the calling process image is set to
290 be ignored by the child process, unless otherwise specified by the
291 .Dv POSIX_SPAWN_SETSIGDEF
292 flag being set in the spawn-flags attribute of the object referenced by
293 .Fa attrp
294 and the signals being indicated in the spawn-sigdefault attribute
295 of the object referenced by
296 .Fa attrp .
297 .Pp
298 If the value of the
299 .Fa attrp
300 pointer is
301 .Dv NULL ,
302 then the default values are used.
303 .Pp
304 All process attributes, other than those influenced by the attributes
305 set in the object referenced by
306 .Fa attrp
307 as specified above or by the file descriptor manipulations specified in
308 .Fa file_actions ,
309 appear in the new process image as though
310 .Fn vfork
311 had been called to create a child process and then
312 .Fn execve
313 had been called by the child process to execute the new process image.
314 .Pp
315 The implementation uses vfork(), thus the fork handlers are not run when
316 .Fn posix_spawn
317 or
318 .Fn posix_spawnp
319 is called.
320 .Sh RETURN VALUES
321 Upon successful completion,
322 .Fn posix_spawn
323 and
324 .Fn posix_spawnp
325 return the process ID of the child process to the parent process,
326 in the variable pointed to by a
327 .Pf non- Dv NULL
328 .Fa pid
329 argument, and return zero as the function return value.
330 Otherwise, no child process is created, no value is stored into
331 the variable pointed to by
332 .Fa pid ,
333 and an error number is returned as the function return value to
334 indicate the error.
335 If the
336 .Fa pid
337 argument is a null pointer, the process ID of the child is not returned
338 to the caller.
339 .Sh ERRORS
340 .Bl -enum
341 .It
342 If
343 .Fn posix_spawn
344 and
345 .Fn posix_spawnp
346 fail for any of the reasons that would cause
347 .Fn vfork
348 or one of the
349 .Nm exec
350 to fail, an error value is returned as described by
351 .Fn vfork
352 and
353 .Nm exec ,
354 respectively (or, if the error occurs after the calling process successfully
355 returns, the child process exits with exit status 127).
356 .It
357 If
358 .Nm POSIX_SPAWN_SETPGROUP
359 is set in the spawn-flags attribute of the object referenced by attrp, and
360 .Fn posix_spawn
361 or
362 .Fn posix_spawnp
363 fails while changing the child's process group, an error value is returned as
364 described by
365 .Fn setpgid
366 (or, if the error occurs after the calling process successfully returns,
367 the child process exits with exit status 127).
368 .It
369 If
370 .Nm POSIX_SPAWN_SETSCHEDPARAM
371 is set and
372 .Nm POSIX_SPAWN_SETSCHEDULER
373 is not set in the spawn-flags attribute of the object referenced by attrp, then
374 if
375 .Fn posix_spawn
376 or
377 .Fn posix_spawnp
378 fails for any of the reasons that would cause
379 .Fn sched_setparam
380 to fail, an error value is returned as described by
381 .Fn sched_setparam
382 (or, if the error occurs after the calling process successfully returns, the
383 child process exits with exit status 127).
384 .It
385 If
386 .Nm POSIX_SPAWN_SETSCHEDULER
387 is set in the spawn-flags attribute of the object referenced by attrp, and if
388 .Fn posix_spawn
389 or
390 .Fn posix_spawnp
391 fails for any of the reasons that would cause
392 .Fn sched_setscheduler
393 to fail, an error value is returned as described by
394 .Fn sched_setscheduler
395 (or, if the error occurs after the calling process successfully returns,
396 the child process exits with exit status 127).
397 .It
398 If the
399 .Fa file_actions
400 argument is not
401 .Dv NULL ,
402 and specifies any
403 .Fn close ,
404 .Fn dup2 ,
405 or
406 .Fn open
407 actions to be performed, and if
408 .Fn posix_spawn
409 or
410 .Fn posix_spawnp
411 fails for any of the reasons that would cause
412 .Fn close ,
413 .Fn dup2 ,
414 or
415 .Fn open
416 to fail, an error value is returned as described by
417 .Fn close ,
418 .Fn dup2 ,
419 and
420 .Fn open ,
421 respectively (or, if the error occurs after the calling process successfully
422 returns, the child process exits with exit status 127). An open file action
423 may, by itself, result in any of the errors described by
424 .Fn close
425 or
426 .Fn dup2 ,
427 in addition to those described by
428 .Fn open .
429 Finally, if the number of
430 .Fa file_actions
431 objects exceeds the allowed limit,
432 .Er EINVAL
433 is returned.
434 .El
435 .Sh SEE ALSO
436 .Xr close 2 ,
437 .Xr dup2 2 ,
438 .Xr execve 2 ,
439 .Xr fcntl 2 ,
440 .Xr open 2 ,
441 .Xr setpgid 2 ,
442 .Xr vfork 2 ,
443 .Xr posix_spawn_file_actions_addclose 3 ,
444 .Xr posix_spawn_file_actions_adddup2 3 ,
445 .Xr posix_spawn_file_actions_addopen 3 ,
446 .Xr posix_spawn_file_actions_destroy 3 ,
447 .Xr posix_spawn_file_actions_init 3 ,
448 .Xr posix_spawnattr_destroy 3 ,
449 .Xr posix_spawnattr_getflags 3 ,
450 .Xr posix_spawnattr_getpgroup 3 ,
451 .Xr posix_spawnattr_getschedparam 3 ,
452 .Xr posix_spawnattr_getschedpolicy 3 ,
453 .Xr posix_spawnattr_getsigdefault 3 ,
454 .Xr posix_spawnattr_getsigmask 3 ,
455 .Xr posix_spawnattr_init 3 ,
456 .Xr posix_spawnattr_setflags 3 ,
457 .Xr posix_spawnattr_setpgroup 3 ,
458 .Xr posix_spawnattr_setschedparam 3 ,
459 .Xr posix_spawnattr_setschedpolicy 3 ,
460 .Xr posix_spawnattr_setsigdefault 3 ,
461 .Xr posix_spawnattr_setsigmask 3 ,
462 .Xr sched_setparam 3 ,
463 .Xr sched_setscheduler 3
464 .Sh STANDARDS
465 The
466 .Fn posix_spawn
467 and
468 .Fn posix_spawnp
469 functions conform to
470 .St -p1003.1-2001 .
471 .Sh HISTORY
472 The
473 .Fn posix_spawn
474 and
475 .Fn posix_spawnp
476 functions first appeared in
477 .Fx 8.0 .
478 The library parts were ported and a kernel implementation of
479 .Fn posix_spawn
480 added for
481 .Nx 6.0
482 during Google Summer of Code by Charles Zhang and Martin Husemann.
483 .Sh AUTHORS
484 .An Ed Schouten Aq Mt ed@FreeBSD.org