Annotation of src/lib/libc/gen/posix_spawn.3, Revision 1.2.2.1
1.2.2.1 ! sborrill 1: .\" $NetBSD: posix_spawn.3,v 1.2 2012/02/13 16:35:59 njoly Exp $
1.1 martin 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
1.2.2.1 ! sborrill 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
1.1 martin 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 .
1.2.2.1 ! sborrill 429: Finally, if the number of
! 430: .Fa file_actions
! 431: objects exceeds the allowed limit,
! 432: .Er EINVAL
! 433: is returned.
1.1 martin 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 ,
1.2 njoly 461: .Xr posix_spawnattr_setsigmask 3 ,
462: .Xr sched_setparam 3 ,
463: .Xr sched_setscheduler 3
1.1 martin 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
482: during Google Summer of Code by Charles Zhang and Martin Husemann.
483: .Sh AUTHORS
484: .An Ed Schouten Aq ed@FreeBSD.org
CVSweb <webmaster@jp.NetBSD.org>