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.
36 .Dt POSIX_SPAWN_FILE_ACTIONS_ADDOPEN 3
39 .Nm posix_spawn_file_actions_addopen ,
40 .Nm posix_spawn_file_actions_adddup2 ,
41 .Nm posix_spawn_file_actions_addclose ,
42 .Nm posix_spawn_file_actions_addclosefrom_np ,
43 .Nm posix_spawn_file_actions_addchdir_np ,
44 .Nm posix_spawn_file_actions_addfchdir_np
45 .Nd "add open, dup2, close, closefrom, or chdir/fchdir actions to spawn file actions object"
51 .Fo posix_spawn_file_actions_addopen
52 .Fa "posix_spawn_file_actions_t * file_actions"
54 .Fa "const char *restrict path"
59 .Fo posix_spawn_file_actions_adddup2
60 .Fa "posix_spawn_file_actions_t * file_actions"
65 .Fo posix_spawn_file_actions_addclose
66 .Fa "posix_spawn_file_actions_t * file_actions"
70 .Fo posix_spawn_file_actions_addclosefrom_np
71 .Fa "posix_spawn_file_actions_t * file_actions"
75 .Fo posix_spawn_file_actions_addchdir_np
76 .Fa "posix_spawn_file_actions_t *restrict file_actions"
77 .Fa "const char *restrict path"
80 .Fo posix_spawn_file_actions_addfchdir_np
81 .Fa "posix_spawn_file_actions_t * file_actions"
85 These functions add an open, dup2 or close action to a spawn
88 A spawn file actions object is of type
89 .Vt posix_spawn_file_actions_t
92 and is used to specify a series of actions to be performed by a
96 operation in order to arrive at the set of open file descriptors for the
97 child process given the set of open file descriptors of the parent.
99 A spawn file actions object, when passed to
103 specify how the set of open file descriptors in the calling
104 process is transformed into a set of potentially open file descriptors
105 for the spawned process.
106 This transformation is as if the specified sequence of actions was
107 performed exactly once, in the context of the spawned process (prior to
108 execution of the new process image), in the order in which the actions
109 were added to the object; additionally, when the new process image is
110 executed, any file descriptor (from this new set) which has its
112 flag set is closed (see
116 .Fn posix_spawn_file_actions_addopen
117 function adds an open action to the object referenced by
119 that causes the file named by
122 .Bd -literal -offset indent
123 open(path, oflag, mode)
126 had been called, and the returned file descriptor, if not
130 when a new process is spawned using this file actions object.
133 was already an open file descriptor, it is closed before the new
136 The string described by
139 .Fn posix_spawn_file_actions_addopen
143 .Fn posix_spawn_file_actions_adddup2
144 function adds a dup2 action to the object referenced by
146 that causes the file descriptor
151 .Bd -literal -offset indent
152 dup2(fildes, newfildes)
155 had been called) when a new process is spawned using this file actions object,
166 is useful for passing a particular file descriptor
167 to a particular child process.
170 .Fn posix_spawn_file_actions_addclose
171 function adds a close action to the object referenced by
173 that causes the file descriptor
176 .Bd -literal -offset indent
180 had been called) when a new process is spawned using this file actions
184 .Fn posix_spawn_file_actions_addclosefrom_np
185 function adds a close action to close all file descriptors numerically
186 equal or greater then the argument
188 For each open file descriptor, logically the close action is performed,
189 and any possible errors encountered are ignored.
192 .Fn posix_spawn_file_actions_addchdir_np
194 .Fn posix_spawn_file_actions_addfchdir_np
195 functions add a change current directory action to the object
198 that affects actions (opens with relative path) performed after the operation,
199 in the order of insertion into the
202 It also sets the working directory for the spawned program.
204 .Fn posix_spawn_file_actions_addchdir_np
207 to set as the working directory, while
208 .Fn posix_spawn_file_actions_addfchdir_np
209 takes the directory file descriptor.
211 Upon successful completion, these functions return zero;
212 otherwise, an error number is returned to indicate the error.
218 The value specified by
224 Insufficient memory exists to add to the spawn file actions object.
231 .Xr posix_spawn_file_actions_destroy 3 ,
232 .Xr posix_spawn_file_actions_init 3 ,
236 .Fn posix_spawn_file_actions_addopen ,
237 .Fn posix_spawn_file_actions_adddup2
239 .Fn posix_spawn_file_actions_addclose
242 with the exception of the behavior of
243 .Fn posix_spawn_file_actions_adddup2
250 A future update of the Standard is expected to require this behavior.
253 .Fn posix_spawn_file_actions_addchdir_np ,
254 .Fn posix_spawn_file_actions_addfchdir_np ,
256 .Fn posix_spawn_file_actions_addclosefrom_np
257 functions are non-standard functions implemented after the similar
258 functionality provided by glibc.
261 .Fn posix_spawn_file_actions_addopen ,
262 .Fn posix_spawn_file_actions_adddup2
264 .Fn posix_spawn_file_actions_addclose
265 functions first appeared in
268 .Fn posix_spawn_file_actions_addchdir_np ,
269 .Fn posix_spawn_file_actions_addfchdir_np ,
271 .Fn posix_spawn_file_actions_addclosefrom_np
272 functions first appeared in
275 .An \&Ed Schouten Aq Mt ed@FreeBSD.org