.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" posix_spawn_file_actions_addclose 
.SH PROLOG
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.
.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 .