1POSIX_SPAWN_FILE_ACTIONS_ADDPCOLSOISXE(P3rPo)grammePrO'SsIXM_aSnPuAaWlN_FILE_ACTIONS_ADDCLOSE(3P)
2
3
4

PROLOG

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
11

NAME

13       posix_spawn_file_actions_addclose,  posix_spawn_file_actions_addopen  —
14       add  close  or open action to spawn file actions object (ADVANCED REAL‐
15       TIME)
16

SYNOPSIS

18       #include <spawn.h>
19
20       int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t
21           *file_actions, int fildes);
22       int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t
23           *restrict file_actions, int fildes,
24           const char *restrict path, int oflag, mode_t mode);
25

DESCRIPTION

27       These functions shall add or delete a close or open action to  a  spawn
28       file actions object.
29
30       A  spawn  file  actions  object  is  of type posix_spawn_file_actions_t
31       (defined in <spawn.h>) and is used to specify a series of actions to be
32       performed  by  a  posix_spawn() or posix_spawnp() operation in order to
33       arrive at the set of open file descriptors for the child process  given
34       the  set of open file descriptors of the parent.  POSIX.1‐2008 does not
35       define   comparison   or   assignment   operators    for    the    type
36       posix_spawn_file_actions_t.
37
38       A   spawn   file  actions  object,  when  passed  to  posix_spawn()  or
39       posix_spawnp(), shall specify how the set of open file  descriptors  in
40       the  calling process is transformed into a set of potentially open file
41       descriptors for the spawned process. This transformation shall be as if
42       the  specified  sequence  of actions was performed exactly once, in the
43       context of the spawned process (prior to execution of the  new  process
44       image),  in  the  order  in which the actions were added to the object;
45       additionally, when the new process image is executed, any file descrip‐
46       tor  (from  this  new  set)  which has its FD_CLOEXEC flag set shall be
47       closed (see posix_spawn()).
48
49       The posix_spawn_file_actions_addclose()  function  shall  add  a  close
50       action  to  the  object referenced by file_actions that shall cause the
51       file descriptor fildes to be  closed  (as  if  close(fildes)  had  been
52       called) when a new process is spawned using this file actions object.
53
54       The  posix_spawn_file_actions_addopen()  function  shall  add  an  open
55       action to the object referenced by file_actions that  shall  cause  the
56       file named by path to be opened (as if open(path, oflag, mode) had been
57       called, and the returned file  descriptor,  if  not  fildes,  had  been
58       changed  to  fildes)  when  a  new  process  is spawned using this file
59       actions object. If fildes was already an open file descriptor, it shall
60       be closed before the new file is opened.
61
62       The    string    described   by   path   shall   be   copied   by   the
63       posix_spawn_file_actions_addopen() function.
64

RETURN VALUE

66       Upon successful completion, these functions shall return  zero;  other‐
67       wise, an error number shall be returned to indicate the error.
68

ERRORS

70       The posix_spawn_file_actions_addopen() function shall fail if:
71
72       EBADF  The  value  specified  by  fildes is negative or greater than or
73              equal to {OPEN_MAX}.
74
75       The posix_spawn_file_actions_addclose() function shall fail if:
76
77       EBADF  The value specified by fildes is negative.
78
79       These functions may fail if:
80
81       EINVAL The value specified by file_actions is invalid.
82
83       ENOMEM Insufficient memory exists to add  to  the  spawn  file  actions
84              object.
85
86       It  shall  not be considered an error for the fildes argument passed to
87       these functions to specify a file descriptor for  which  the  specified
88       operation  could  not  be  performed  at the time of the call. Any such
89       error will be detected when the associated file actions object is later
90       used during a posix_spawn() or posix_spawnp() operation.
91
92       The following sections are informative.
93

EXAMPLES

95       None.
96

APPLICATION USAGE

98       These  functions  are part of the Spawn option and need not be provided
99       on all implementations.
100
101       Implementations may use file descriptors that must  be  inherited  into
102       child processes for the child process to remain conforming, such as for
103       message catalog or tracing purposes.  Therefore,  an  application  that
104       calls  posix_spawn_file_actions_addclose()  with  an  arbitrary integer
105       risks non-conforming behavior, and this function can only  portably  be
106       used  to close file descriptor values that the application has obtained
107       through explicit actions, or for the three file descriptors correspond‐
108       ing to the standard file streams. In order to avoid a race condition of
109       leaking an unintended file descriptor into a child process, an applica‐
110       tion  should  consider opening all file descriptors with the FD_CLOEXEC
111       bit set unless the file descriptor is intended to be  inherited  across
112       exec.
113

RATIONALE

115       A  spawn  file  actions object may be initialized to contain an ordered
116       sequence of close(), dup2(),  and  open()  operations  to  be  used  by
117       posix_spawn()  or  posix_spawnp()  to  arrive  at  the set of open file
118       descriptors inherited by the spawned process from the set of open  file
119       descriptors  in  the  parent  at  the  time  of  the  posix_spawn()  or
120       posix_spawnp() call. It had been suggested that the close() and  dup2()
121       operations alone are sufficient to rearrange file descriptors, and that
122       files which need to be opened for use by the  spawned  process  can  be
123       handled  either  by  having  the  calling  process open them before the
124       posix_spawn() or posix_spawnp() call (and  close  them  after),  or  by
125       passing  pathnames to the spawned process (in argv) so that it may open
126       them itself. The standard developers recommend  that  applications  use
127       one of these two methods when practical, since detailed error status on
128       a failed open operation is always available  to  the  application  this
129       way.  However,  the standard developers feel that allowing a spawn file
130       actions object to specify open operations is still appropriate because:
131
132        1. It is consistent with equivalent POSIX.5 (Ada) functionality.
133
134        2. It supports the I/O redirection paradigm commonly employed by POSIX
135           programs  designed  to be invoked from a shell. When such a program
136           is the child process, it may not be designed to open files  on  its
137           own.
138
139        3. It allows file opens that might otherwise fail or violate file own‐
140           ership/access rights if executed by the parent process.
141
142       Regarding 2. above, note that the spawn open file  action  provides  to
143       posix_spawn() and posix_spawnp() the same capability that the shell re‐
144       direction operators provide to system(), only without  the  intervening
145       execution of a shell; for example:
146
147           system ("myprog <file1 3<file2");
148
149       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
155       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
165   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
176       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
186       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

FUTURE DIRECTIONS

197       None.
198

SEE ALSO

200       close(), dup(), open(), posix_spawn(),
201       posix_spawn_file_actions_adddup2(), posix_spawn_file_actions_destroy()
202
203       The Base Definitions volume of POSIX.1‐2008, <spawn.h>
204
206       Portions of this text are reprinted and reproduced in  electronic  form
207       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
208       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
209       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
210       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
211       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
212       event of any discrepancy between this version and the original IEEE and
213       The  Open Group Standard, the original IEEE and The Open Group Standard
214       is the referee document. The original Standard can be  obtained  online
215       at http://www.unix.org/online.html .
216
217       Any  typographical  or  formatting  errors that appear in this page are
218       most likely to have been introduced during the conversion of the source
219       files  to  man page format. To report such errors, see https://www.ker
220       nel.org/doc/man-pages/reporting_bugs.html .
221
222
223
224IEEE/The Open Group                  2013POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE(3P)
Impressum