|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
|
|
|
POSIX_S...ADDCLOSE(3P) POSIX Programmer's Manual POSIX_S...ADDCLOSE(3P)
This manual page is part of the POSIX Programmer's Manual. The
Linux implementation of this interface may differ (consult the
corresponding Linux manual page for details of Linux behavior), or
the interface may not be implemented on Linux.
posix_spawn_file_actions_addclose,
posix_spawn_file_actions_addopen — add close or open action to
spawn file actions object (ADVANCED REALTIME)
#include <spawn.h>
int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t
*file_actions, int fildes);
int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t
*restrict file_actions, int fildes,
const char *restrict path, int oflag, mode_t mode);
These functions shall add or delete a close or open action to a
spawn file actions object.
A spawn file actions object is of type posix_spawn_file_actions_t
(defined in <spawn.h>) and is used to specify a series of actions
to be performed by a posix_spawn() or posix_spawnp() operation in
order to arrive at the set of open file descriptors for the child
process given the set of open file descriptors of the parent.
POSIX.1‐2008 does not define comparison or assignment operators
for the type posix_spawn_file_actions_t.
A spawn file actions object, when passed to posix_spawn() or
posix_spawnp(), shall specify how the set of open file descriptors
in the calling process is transformed into a set of potentially
open file descriptors for the spawned process. This transformation
shall be as if the specified sequence of actions was performed
exactly once, in the context of the spawned process (prior to
execution of the new process image), in the order in which the
actions were added to the object; additionally, when the new
process image is executed, any file descriptor (from this new set)
which has its FD_CLOEXEC flag set shall be closed (see
posix_spawn(3p)).
The posix_spawn_file_actions_addclose() function shall add a close
action to the object referenced by file_actions that shall cause
the file descriptor fildes to be closed (as if close(fildes) had
been called) when a new process is spawned using this file actions
object.
The posix_spawn_file_actions_addopen() function shall add an open
action to the object referenced by file_actions that shall cause
the file named by path to be opened (as if open(path, oflag, mode)
had been called, and the returned file descriptor, if not fildes,
had been changed to fildes) when a new process is spawned using
this file actions object. If fildes was already an open file
descriptor, it shall be closed before the new file is opened.
The string described by path shall be copied by the
posix_spawn_file_actions_addopen() function.
Upon successful completion, these functions shall return zero;
otherwise, an error number shall be returned to indicate the
error.
The posix_spawn_file_actions_addopen() function shall fail if:
EBADF The value specified by fildes is negative or greater than
or equal to {OPEN_MAX}.
The posix_spawn_file_actions_addclose() function shall fail if:
EBADF The value specified by fildes is negative.
These functions may fail if:
EINVAL The value specified by file_actions is invalid.
ENOMEM Insufficient memory exists to add to the spawn file actions
object.
It shall not be considered an error for the fildes argument passed
to these functions to specify a file descriptor for which the
specified operation could not be performed at the time of the
call. Any such error will be detected when the associated file
actions object is later used during a posix_spawn() or
posix_spawnp() operation.
The following sections are informative.
None.
These functions are part of the Spawn option and need not be
provided on all implementations.
Implementations may use file descriptors that must be inherited
into child processes for the child process to remain conforming,
such as for message catalog or tracing purposes. Therefore, an
application that calls posix_spawn_file_actions_addclose() with an
arbitrary integer risks non-conforming behavior, and this function
can only portably be used to close file descriptor values that the
application has obtained through explicit actions, or for the
three file descriptors corresponding to the standard file streams.
In order to avoid a race condition of leaking an unintended file
descriptor into a child process, an application should consider
opening all file descriptors with the FD_CLOEXEC bit set unless
the file descriptor is intended to be inherited across exec.
A spawn file actions object may be initialized to contain an
ordered sequence of close(), dup2(), and open() operations to be
used by posix_spawn() or posix_spawnp() to arrive at the set of
open file descriptors inherited by the spawned process from the
set of open file descriptors in the parent at the time of the
posix_spawn() or posix_spawnp() call. It had been suggested that
the close() and dup2() operations alone are sufficient to
rearrange file descriptors, and that files which need to be opened
for use by the spawned process can be handled either by having the
calling process open them before the posix_spawn() or
posix_spawnp() call (and close them after), or by passing
pathnames to the spawned process (in argv) so that it may open
them itself. The standard developers recommend that applications
use one of these two methods when practical, since detailed error
status on a failed open operation is always available to the
application this way. However, the standard developers feel that
allowing a spawn file actions object to specify open operations is
still appropriate because:
1. It is consistent with equivalent POSIX.5 (Ada) functionality.
2. It supports the I/O redirection paradigm commonly employed by
POSIX programs designed to be invoked from a shell. When such
a program is the child process, it may not be designed to open
files on its own.
3. It allows file opens that might otherwise fail or violate file
ownership/access rights if executed by the parent process.
Regarding 2. above, note that the spawn open file action provides
to posix_spawn() and posix_spawnp() the same capability that the
shell redirection operators provide to system(), only without the
intervening execution of a shell; for example:
system ("myprog <file1 3<file2");
Regarding 3. above, note that if the calling process needs to open
one or more files for access by the spawned process, but has
insufficient spare file descriptors, then the open action is
necessary to allow the open() to occur in the context of the child
process after other file descriptors have been closed (that must
remain open in the parent).
Additionally, if a parent is executed from a file having a ``set-
user-id'' mode bit set and the POSIX_SPAWN_RESETIDS flag is set in
the spawn attributes, a file created within the parent process
will (possibly incorrectly) have the parent's effective user ID as
its owner, whereas a file created via an open() action during
posix_spawn() or posix_spawnp() will have the parent's real ID as
its owner; and an open by the parent process may successfully open
a file to which the real user should not have access or fail to
open a file to which the real user should have access.
File Descriptor Mapping
The standard developers had originally proposed using an array
which specified the mapping of child file descriptors back to
those of the parent. It was pointed out by the ballot group that
it is not possible to reshuffle file descriptors arbitrarily in a
library implementation of posix_spawn() or posix_spawnp() without
provision for one or more spare file descriptor entries (which
simply may not be available). Such an array requires that an
implementation develop a complex strategy to achieve the desired
mapping without inadvertently closing the wrong file descriptor at
the wrong time.
It was noted by a member of the Ada Language Bindings working
group that the approved Ada Language Start_Process family of POSIX
process primitives use a caller-specified set of file actions to
alter the normal fork()/exec semantics for inheritance of file
descriptors in a very flexible way, yet no such problems exist
because the burden of determining how to achieve the final file
descriptor mapping is completely on the application. Furthermore,
although the file actions interface appears frightening at first
glance, it is actually quite simple to implement in either a
library or the kernel.
The posix_spawn_file_actions_addclose() function is not required
to check whether the file descriptor is less than {OPEN_MAX}
because on some implementations {OPEN_MAX} reflects the
RLIMIT_NOFILE soft limit and therefore calling setrlimit() to
reduce this limit can result in an {OPEN_MAX} value less than or
equal to an already open file descriptor. Applications need to be
able to close such file descriptors on spawn. On implementations
where {OPEN_MAX} does not change, it is recommended that
posix_spawn_file_actions_addclose() should return [EBADF] if
fildes is greater than or equal to {OPEN_MAX}.
None.
close(3p), dup(3p), open(3p), posix_spawn(3p),
posix_spawn_file_actions_adddup2(3p),
posix_spawn_file_actions_destroy(3p)
The Base Definitions volume of POSIX.1‐2017, spawn.h(0p)
Portions of this text are reprinted and reproduced in electronic
form from IEEE Std 1003.1-2017, Standard for Information
Technology -- Portable Operating System Interface (POSIX), The
Open Group Base Specifications Issue 7, 2018 Edition, Copyright
(C) 2018 by the Institute of Electrical and Electronics Engineers,
Inc and The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group Standard,
the original IEEE and The Open Group Standard is the referee
document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
Any typographical or formatting errors that appear in this page
are most likely to have been introduced during the conversion of
the source files to man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2017 POSIX_S...ADDCLOSE(3P)
Pages that refer to this page: spawn.h(0p), posix_spawn(3p), posix_spawn_file_actions_adddup2(3p), posix_spawn_file_actions_addopen(3p), posix_spawn_file_actions_destroy(3p)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|