mirror of https://github.com/mkerrisk/man-pages
219 lines
8.9 KiB
Plaintext
219 lines
8.9 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" posix_spawn_file_actions_addclose
|
||
|
.SH NAME
|
||
|
posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen
|
||
|
\- add close or open action to spawn file actions
|
||
|
object (\fBADVANCED REALTIME\fP)
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <spawn.h>
|
||
|
.br
|
||
|
.sp
|
||
|
int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t *
|
||
|
.br
|
||
|
\ \ \ \ \ \ \fP \fIfile_actions\fP\fB, int\fP \fIfildes\fP\fB);
|
||
|
.br
|
||
|
int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *
|
||
|
.br
|
||
|
\ \ \ \ \ \ restrict\fP \fIfile_actions\fP\fB, int\fP \fIfildes\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ const char *restrict\fP \fIpath\fP\fB, int\fP \fIoflag\fP\fB,
|
||
|
mode_t\fP
|
||
|
\fImode\fP\fB); \fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
These functions shall add or delete a close or open action to a spawn
|
||
|
file actions object.
|
||
|
.LP
|
||
|
A spawn file actions object is of type \fBposix_spawn_file_actions_t\fP
|
||
|
(defined in \fI<spawn.h>\fP) and is used to specify a series of actions
|
||
|
to be performed by a \fIposix_spawn\fP() or \fIposix_spawnp\fP()
|
||
|
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. IEEE\ Std\ 1003.1-2001 does not define comparison or assignment
|
||
|
operators for the type
|
||
|
\fBposix_spawn_file_actions_t\fP.
|
||
|
.LP
|
||
|
A spawn file actions object, when passed to \fIposix_spawn\fP() or
|
||
|
\fIposix_spawnp\fP(), 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 \fIposix_spawn\fP() ).
|
||
|
.LP
|
||
|
The \fIposix_spawn_file_actions_addclose\fP() function shall add a
|
||
|
\fIclose\fP action to the object referenced by
|
||
|
\fIfile_actions\fP that shall cause the file descriptor \fIfildes\fP
|
||
|
to be closed (as if \fIclose\fP( \fIfildes\fP) had been
|
||
|
called) when a new process is spawned using this file actions object.
|
||
|
.LP
|
||
|
The \fIposix_spawn_file_actions_addopen\fP() function shall add an
|
||
|
\fIopen\fP action to the object referenced by
|
||
|
\fIfile_actions\fP that shall cause the file named by \fIpath\fP to
|
||
|
be opened (as if \fIopen\fP( \fIpath\fP, \fIoflag\fP,
|
||
|
\fImode\fP) had been called, and the returned file descriptor, if
|
||
|
not \fIfildes\fP, had been changed to \fIfildes\fP) when a new
|
||
|
process is spawned using this file actions object. If \fIfildes\fP
|
||
|
was already an open file descriptor, it shall be closed before
|
||
|
the new file is opened.
|
||
|
.LP
|
||
|
The string described by \fIpath\fP shall be copied by the \fIposix_spawn_file_actions_addopen\fP()
|
||
|
function.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
Upon successful completion, these functions shall return zero; otherwise,
|
||
|
an error number shall be returned to indicate the
|
||
|
error.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
These functions shall fail if:
|
||
|
.TP 7
|
||
|
.B EBADF
|
||
|
The value specified by \fIfildes\fP is negative or greater than or
|
||
|
equal to {OPEN_MAX}.
|
||
|
.sp
|
||
|
.LP
|
||
|
These functions may fail if:
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The value specified by \fIfile_actions\fP is invalid.
|
||
|
.TP 7
|
||
|
.B ENOMEM
|
||
|
Insufficient memory exists to add to the spawn file actions object.
|
||
|
.sp
|
||
|
.LP
|
||
|
It shall not be considered an error for the \fIfildes\fP 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 \fIposix_spawn\fP() or
|
||
|
\fIposix_spawnp\fP() operation.
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
These functions are part of the Spawn option and need not be provided
|
||
|
on all implementations.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
A spawn file actions object may be initialized to contain an ordered
|
||
|
sequence of \fIclose\fP(), \fIdup2\fP(), and \fIopen\fP() operations
|
||
|
to be used by \fIposix_spawn\fP() or \fIposix_spawnp\fP() 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 \fIposix_spawn\fP() or \fIposix_spawnp\fP() call.
|
||
|
It had been suggested that the \fIclose\fP() and \fIdup2\fP() 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 \fIposix_spawn\fP()
|
||
|
or \fIposix_spawnp\fP() call (and close them after), or by passing
|
||
|
filenames to the spawned
|
||
|
process (in \fIargv\fP) 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:
|
||
|
.IP " 1." 4
|
||
|
It is consistent with equivalent POSIX.5 (Ada) functionality.
|
||
|
.LP
|
||
|
.IP " 2." 4
|
||
|
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.
|
||
|
.LP
|
||
|
.IP " 3." 4
|
||
|
It allows file opens that might otherwise fail or violate file ownership/access
|
||
|
rights if executed by the parent process.
|
||
|
.LP
|
||
|
.LP
|
||
|
Regarding 2. above, note that the spawn open file action provides
|
||
|
to \fIposix_spawn\fP() and \fIposix_spawnp\fP() the
|
||
|
same capability that the shell redirection operators provide to \fIsystem\fP(),
|
||
|
only
|
||
|
without the intervening execution of a shell; for example:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBsystem ("myprog <file1 3<file2");
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
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 \fIopen\fP() to occur in the context of the child process
|
||
|
after other file descriptors have been
|
||
|
closed (that must remain open in the parent).
|
||
|
.LP
|
||
|
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 \fIopen\fP() action during
|
||
|
\fIposix_spawn\fP() or \fIposix_spawnp\fP() 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.
|
||
|
.SS File Descriptor Mapping
|
||
|
.LP
|
||
|
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 \fIposix_spawn\fP() or \fIposix_spawnp\fP()
|
||
|
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.
|
||
|
.LP
|
||
|
It was noted by a member of the Ada Language Bindings working group
|
||
|
that the approved Ada Language \fIStart_Process\fP family
|
||
|
of POSIX process primitives use a caller-specified set of file actions
|
||
|
to alter the normal \fIfork\fP()/ \fIexec\fP 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.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIclose\fP() , \fIdup\fP() , \fIopen\fP() , \fIposix_spawn\fP() ,
|
||
|
\fIposix_spawn_file_actions_adddup2\fP() , \fIposix_spawn_file_actions_destroy\fP()
|
||
|
, \fIposix_spawnp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
||
|
\fI<spawn.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|