1POSIX_SPAWN_FILE_ACTIONS_ADDPCOLSOISXE(P3rPo)grammePrO'SsIXM_aSnPuAaWlN_FILE_ACTIONS_ADDCLOSE(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen —
13 add close or open action to spawn file actions object (ADVANCED REAL‐
14 TIME)
15
17 #include <spawn.h>
18 int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t
20 *file_actions, int fildes);
21 int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t
22 *restrict file_actions, int fildes,
23 const char *restrict path, int oflag, mode_t mode);
24
26 These functions shall add or delete a close or open action to a spawn
27 file actions object.
28 A spawn file actions object is of type posix_spawn_file_actions_t
30 (defined in <spawn.h>) and is used to specify a series of actions to be
31 performed by a posix_spawn() or posix_spawnp() operation in order to
32 arrive at the set of open file descriptors for the child process given
33 the set of open file descriptors of the parent. POSIX.1‐2008 does not
34 define comparison or assignment operators for the type
35 posix_spawn_file_actions_t.
36 A spawn file actions object, when passed to posix_spawn() or
38 posix_spawnp(), shall specify how the set of open file descriptors in
39 the calling process is transformed into a set of potentially open file
40 descriptors for the spawned process. This transformation shall be as if
41 the specified sequence of actions was performed exactly once, in the
42 context of the spawned process (prior to execution of the new process
43 image), in the order in which the actions were added to the object;
44 additionally, when the new process image is executed, any file descrip‐
45 tor (from this new set) which has its FD_CLOEXEC flag set shall be
46 closed (see posix_spawn()).
47 The posix_spawn_file_actions_addclose() function shall add a close
49 action to the object referenced by file_actions that shall cause the
50 file descriptor fildes to be closed (as if close(fildes) had been
51 called) when a new process is spawned using this file actions object.
52 The posix_spawn_file_actions_addopen() function shall add an open
54 action to the object referenced by file_actions that shall cause the
55 file named by path to be opened (as if open(path, oflag, mode) had been
56 called, and the returned file descriptor, if not fildes, had been
57 changed to fildes) when a new process is spawned using this file
58 actions object. If fildes was already an open file descriptor, it shall
59 be closed before the new file is opened.
60 The string described by path shall be copied by the
62 posix_spawn_file_actions_addopen() function.
63
65 Upon successful completion, these functions shall return zero; other‐
66 wise, an error number shall be returned to indicate the error.
67
69 The posix_spawn_file_actions_addopen() function shall fail if:
70 EBADF The value specified by fildes is negative or greater than or
72 equal to {OPEN_MAX}.
73 The posix_spawn_file_actions_addclose() function shall fail if:
75 EBADF The value specified by fildes is negative.
77 These functions may fail if:
79 EINVAL The value specified by file_actions is invalid.
81 ENOMEM Insufficient memory exists to add to the spawn file actions
83 object.
84 It shall not be considered an error for the fildes argument passed to
86 these functions to specify a file descriptor for which the specified
87 operation could not be performed at the time of the call. Any such
88 error will be detected when the associated file actions object is later
89 used during a posix_spawn() or posix_spawnp() operation.
90 The following sections are informative.
92
94 None.
95
97 These functions are part of the Spawn option and need not be provided
98 on all implementations.
99 Implementations may use file descriptors that must be inherited into
101 child processes for the child process to remain conforming, such as for
102 message catalog or tracing purposes. Therefore, an application that
103 calls posix_spawn_file_actions_addclose() with an arbitrary integer
104 risks non-conforming behavior, and this function can only portably be
105 used to close file descriptor values that the application has obtained
106 through explicit actions, or for the three file descriptors correspond‐
107 ing to the standard file streams. In order to avoid a race condition of
108 leaking an unintended file descriptor into a child process, an applica‐
109 tion should consider opening all file descriptors with the FD_CLOEXEC
110 bit set unless the file descriptor is intended to be inherited across
111 exec.
112
114 A spawn file actions object may be initialized to contain an ordered
115 sequence of close(), dup2(), and open() operations to be used by
116 posix_spawn() or posix_spawnp() to arrive at the set of open file
117 descriptors inherited by the spawned process from the set of open file
118 descriptors in the parent at the time of the posix_spawn() or
119 posix_spawnp() call. It had been suggested that the close() and dup2()
120 operations alone are sufficient to rearrange file descriptors, and that
121 files which need to be opened for use by the spawned process can be
122 handled either by having the calling process open them before the
123 posix_spawn() or posix_spawnp() call (and close them after), or by
124 passing pathnames to the spawned process (in argv) so that it may open
125 them itself. The standard developers recommend that applications use
126 one of these two methods when practical, since detailed error status on
127 a failed open operation is always available to the application this
128 way. However, the standard developers feel that allowing a spawn file
129 actions object to specify open operations is still appropriate because:
130 1. It is consistent with equivalent POSIX.5 (Ada) functionality.
132 2. It supports the I/O redirection paradigm commonly employed by POSIX
134 programs designed to be invoked from a shell. When such a program
135 is the child process, it may not be designed to open files on its
136 own.
137 3. It allows file opens that might otherwise fail or violate file own‐
139 ership/access rights if executed by the parent process.
140 Regarding 2. above, note that the spawn open file action provides to
142 posix_spawn() and posix_spawnp() the same capability that the shell re‐
143 direction operators provide to system(), only without the intervening
144 execution of a shell; for example:
145 system ("myprog <file1 3<file2");
148 Regarding 3. above, note that if the calling process needs to open one
150 or more files for access by the spawned process, but has insufficient
151 spare file descriptors, then the open action is necessary to allow the
152 open() to occur in the context of the child process after other file
153 descriptors have been closed (that must remain open in the parent).
154 Additionally, if a parent is executed from a file having a ``set-user-
156 id'' mode bit set and the POSIX_SPAWN_RESETIDS flag is set in the spawn
157 attributes, a file created within the parent process will (possibly
158 incorrectly) have the parent's effective user ID as its owner, whereas
159 a file created via an open() action during posix_spawn() or
160 posix_spawnp() will have the parent's real ID as its owner; and an open
161 by the parent process may successfully open a file to which the real
162 user should not have access or fail to open a file to which the real
163 user should have access.
164 File Descriptor Mapping
166 The standard developers had originally proposed using an array which
167 specified the mapping of child file descriptors back to those of the
168 parent. It was pointed out by the ballot group that it is not possible
169 to reshuffle file descriptors arbitrarily in a library implementation
170 of posix_spawn() or posix_spawnp() without provision for one or more
171 spare file descriptor entries (which simply may not be available). Such
172 an array requires that an implementation develop a complex strategy to
173 achieve the desired mapping without inadvertently closing the wrong
174 file descriptor at the wrong time.
175 It was noted by a member of the Ada Language Bindings working group
177 that the approved Ada Language Start_Process family of POSIX process
178 primitives use a caller-specified set of file actions to alter the nor‐
179 mal fork()/exec semantics for inheritance of file descriptors in a very
180 flexible way, yet no such problems exist because the burden of deter‐
181 mining how to achieve the final file descriptor mapping is completely
182 on the application. Furthermore, although the file actions interface
183 appears frightening at first glance, it is actually quite simple to
184 implement in either a library or the kernel.
185 The posix_spawn_file_actions_addclose() function is not required to
187 check whether the file descriptor is less than {OPEN_MAX} because on
188 some implementations {OPEN_MAX} reflects the RLIMIT_NOFILE soft limit
189 and therefore calling setrlimit() to reduce this limit can result in an
190 {OPEN_MAX} value less than or equal to an already open file descriptor.
191 Applications need to be able to close such file descriptors on spawn.
192 On implementations where {OPEN_MAX} does not change, it is recommended
193 that posix_spawn_file_actions_addclose() should return [EBADF] if
194 fildes is greater than or equal to {OPEN_MAX}.
195
197 None.
198
200 close(), dup(), open(), posix_spawn(),
201 posix_spawn_file_actions_adddup2(), posix_spawn_file_actions_destroy()
202 The Base Definitions volume of POSIX.1‐2017, <spawn.h>
204
206 Portions of this text are reprinted and reproduced in electronic form
207 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
208 table Operating System Interface (POSIX), The Open Group Base Specifi‐
209 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
210 Electrical and Electronics Engineers, Inc and The Open Group. In the
211 event of any discrepancy between this version and the original IEEE and
212 The Open Group Standard, the original IEEE and The Open Group Standard
213 is the referee document. The original Standard can be obtained online
214 at http://www.opengroup.org/unix/online.html .
215 Any typographical or formatting errors that appear in this page are
217 most likely to have been introduced during the conversion of the source
218 files to man page format. To report such errors, see https://www.ker‐
219 nel.org/doc/man-pages/reporting_bugs.html .
220IEEE/The Open Group 2017POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE(3P)