1 files changed, 218 insertions, 0 deletions
diff --git a/man3p/posix_spawn_file_actions_addopen.3p b/man3p/posix_spawn_file_actions_addopen.3p
new file mode 100644
index 000000000..b377b5399
--- /dev/null
+++ b/man3p/posix_spawn_file_actions_addopen.3p
@@ -0,0 +1,218 @@
+.\" 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 .