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