1POSIX_SPAWN_FILE_ACTIONS_ADDPCOLSOISXE(PPr)ogrammerP'OsSIMXa_nSuPaAlWN_FILE_ACTIONS_ADDCLOSE(P)
2
6 posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen -
7 add close or open action to spawn file actions object (ADVANCED REAL‐
8 TIME)
9
11 #include <spawn.h>
12 int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t *
14 file_actions, int fildes);
15 int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *
16 restrict file_actions, int fildes,
17 const char *restrict path, int oflag, mode_t mode);
18
21 These functions shall add or delete a close or open action to a spawn
22 file actions object.
23 A spawn file actions object is of type posix_spawn_file_actions_t
25 (defined in <spawn.h>) and is used to specify a series of actions to be
26 performed by a posix_spawn() or posix_spawnp() operation in order to
27 arrive at the set of open file descriptors for the child process given
28 the set of open file descriptors of the parent. IEEE Std 1003.1-2001
29 does not define comparison or assignment operators for the type
30 posix_spawn_file_actions_t.
31 A spawn file actions object, when passed to posix_spawn() or
33 posix_spawnp(), shall specify how the set of open file descriptors in
34 the calling process is transformed into a set of potentially open file
35 descriptors for the spawned process. This transformation shall be as if
36 the specified sequence of actions was performed exactly once, in the
37 context of the spawned process (prior to execution of the new process
38 image), in the order in which the actions were added to the object;
39 additionally, when the new process image is executed, any file descrip‐
40 tor (from this new set) which has its FD_CLOEXEC flag set shall be
41 closed (see posix_spawn() ).
42 The posix_spawn_file_actions_addclose() function shall add a close
44 action to the object referenced by file_actions that shall cause the
45 file descriptor fildes to be closed (as if close( fildes) had been
46 called) when a new process is spawned using this file actions object.
47 The posix_spawn_file_actions_addopen() function shall add an open
49 action to the object referenced by file_actions that shall cause the
50 file named by path to be opened (as if open( path, oflag, mode) had
51 been called, and the returned file descriptor, if not fildes, had been
52 changed to fildes) when a new process is spawned using this file
53 actions object. If fildes was already an open file descriptor, it shall
54 be closed before the new file is opened.
55 The string described by path shall be copied by the
57 posix_spawn_file_actions_addopen() function.
58
60 Upon successful completion, these functions shall return zero; other‐
61 wise, an error number shall be returned to indicate the error.
62
64 These functions shall fail if:
65 EBADF The value specified by fildes is negative or greater than or
67 equal to {OPEN_MAX}.
68 These functions may fail if:
71 EINVAL The value specified by file_actions is invalid.
73 ENOMEM Insufficient memory exists to add to the spawn file actions
75 object.
76 It shall not be considered an error for the fildes argument passed to
79 these functions to specify a file descriptor for which the specified
80 operation could not be performed at the time of the call. Any such
81 error will be detected when the associated file actions object is later
82 used during a posix_spawn() or posix_spawnp() operation.
83 The following sections are informative.
85
87 None.
88
90 These functions are part of the Spawn option and need not be provided
91 on all implementations.
92
94 A spawn file actions object may be initialized to contain an ordered
95 sequence of close(), dup2(), and open() operations to be used by
96 posix_spawn() or posix_spawnp() to arrive at the set of open file
97 descriptors inherited by the spawned process from the set of open file
98 descriptors in the parent at the time of the posix_spawn() or
99 posix_spawnp() call. It had been suggested that the close() and dup2()
100 operations alone are sufficient to rearrange file descriptors, and that
101 files which need to be opened for use by the spawned process can be
102 handled either by having the calling process open them before the
103 posix_spawn() or posix_spawnp() call (and close them after), or by
104 passing filenames to the spawned process (in argv) so that it may open
105 them itself. The standard developers recommend that applications use
106 one of these two methods when practical, since detailed error status on
107 a failed open operation is always available to the application this
108 way. However, the standard developers feel that allowing a spawn file
109 actions object to specify open operations is still appropriate because:
110 1. It is consistent with equivalent POSIX.5 (Ada) functionality.
112 2. It supports the I/O redirection paradigm commonly employed by POSIX
114 programs designed to be invoked from a shell. When such a program
115 is the child process, it may not be designed to open files on its
116 own.
117 3. It allows file opens that might otherwise fail or violate file own‐
119 ership/access rights if executed by the parent process.
120 Regarding 2. above, note that the spawn open file action provides to
122 posix_spawn() and posix_spawnp() the same capability that the shell re‐
123 direction operators provide to system(), only without the intervening
124 execution of a shell; for example:
125 system ("myprog <file1 3<file2");
128 Regarding 3. above, note that if the calling process needs to open one
130 or more files for access by the spawned process, but has insufficient
131 spare file descriptors, then the open action is necessary to allow the
132 open() to occur in the context of the child process after other file
133 descriptors have been closed (that must remain open in the parent).
134 Additionally, if a parent is executed from a file having a "set-user-
136 id" mode bit set and the POSIX_SPAWN_RESETIDS flag is set in the spawn
137 attributes, a file created within the parent process will (possibly
138 incorrectly) have the parent's effective user ID as its owner, whereas
139 a file created via an open() action during posix_spawn() or
140 posix_spawnp() will have the parent's real ID as its owner; and an open
141 by the parent process may successfully open a file to which the real
142 user should not have access or fail to open a file to which the real
143 user should have access.
144 File Descriptor Mapping
146 The standard developers had originally proposed using an array which
147 specified the mapping of child file descriptors back to those of the
148 parent. It was pointed out by the ballot group that it is not possible
149 to reshuffle file descriptors arbitrarily in a library implementation
150 of posix_spawn() or posix_spawnp() without provision for one or more
151 spare file descriptor entries (which simply may not be available). Such
152 an array requires that an implementation develop a complex strategy to
153 achieve the desired mapping without inadvertently closing the wrong
154 file descriptor at the wrong time.
155 It was noted by a member of the Ada Language Bindings working group
157 that the approved Ada Language Start_Process family of POSIX process
158 primitives use a caller-specified set of file actions to alter the nor‐
159 mal fork()/ exec semantics for inheritance of file descriptors in a
160 very flexible way, yet no such problems exist because the burden of
161 determining how to achieve the final file descriptor mapping is com‐
162 pletely on the application. Furthermore, although the file actions
163 interface appears frightening at first glance, it is actually quite
164 simple to implement in either a library or the kernel.
165
167 None.
168
170 close() , dup() , open() , posix_spawn() ,
171 posix_spawn_file_actions_adddup2() , posix_spawn_file_actions_destroy()
172 , posix_spawnp() , the Base Definitions volume of IEEE Std 1003.1-2001,
173 <spawn.h>
174
176 Portions of this text are reprinted and reproduced in electronic form
177 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
178 -- Portable Operating System Interface (POSIX), The Open Group Base
179 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
180 Electrical and Electronics Engineers, Inc and The Open Group. In the
181 event of any discrepancy between this version and the original IEEE and
182 The Open Group Standard, the original IEEE and The Open Group Standard
183 is the referee document. The original Standard can be obtained online
184 at http://www.opengroup.org/unix/online.html .
185IEEE/The Open Group 2003 POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE(P)