posix_spawn_file_actions_addclose.3p (11024B)
- '\" et
- .TH POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .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
- \(em add close or open action to spawn file actions object
- (\fBADVANCED REALTIME\fP)
- .SH SYNOPSIS
- .LP
- .nf
- #include <spawn.h>
- .P
- int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t
- *\fIfile_actions\fP, int \fIfildes\fP);
- int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t
- *restrict \fIfile_actions\fP, int \fIfildes\fP,
- const char *restrict \fIpath\fP, int \fIoflag\fP, mode_t \fImode\fP);
- .fi
- .SH DESCRIPTION
- These functions shall add or delete a close or open action to a
- spawn file actions object.
- .P
- A spawn file actions object is of type
- .BR posix_spawn_file_actions_t
- (defined in
- .IR <spawn.h> )
- and is used to specify a series of actions to be performed by a
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- 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\(hy2008 does not define comparison or assignment operators for the type
- .BR posix_spawn_file_actions_t .
- .P
- A spawn file actions object, when passed to
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR(),
- 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
- .IR "\fIposix_spawn\fR\^(\|)").
- .P
- The
- \fIposix_spawn_file_actions_addclose\fR()
- function shall add a
- .IR close
- action to the object referenced by
- .IR file_actions
- that shall cause the file descriptor
- .IR fildes
- to be closed (as if
- .IR close (\c
- .IR fildes )
- had been called) when a new process is spawned using this file actions
- object.
- .P
- The
- \fIposix_spawn_file_actions_addopen\fR()
- function shall add an
- .IR open
- action to the object referenced by
- .IR file_actions
- that shall cause the file named by
- .IR path
- to be opened (as if
- .IR open (\c
- .IR path ,
- .IR oflag ,
- .IR mode )
- had been called, and the returned file descriptor, if not
- .IR fildes ,
- had been changed to
- .IR fildes )
- when a new process is spawned using this file actions object. If
- .IR fildes
- was already an open file descriptor, it shall be closed before the new
- file is opened.
- .P
- The string described by
- .IR path
- shall be copied by the
- \fIposix_spawn_file_actions_addopen\fR()
- function.
- .SH "RETURN VALUE"
- Upon successful completion, these functions shall return zero;
- otherwise, an error number shall be returned to indicate the error.
- .SH ERRORS
- The
- \fIposix_spawn_file_actions_addopen\fR()
- function shall fail if:
- .TP
- .BR EBADF
- The value specified by
- .IR fildes
- is negative or greater than or equal to
- {OPEN_MAX}.
- .P
- The
- \fIposix_spawn_file_actions_addclose\fR()
- function shall fail if:
- .TP
- .BR EBADF
- The value specified by
- .IR fildes
- is negative.
- .br
- .P
- These functions may fail if:
- .TP
- .BR EINVAL
- The value specified by
- .IR file_actions
- is invalid.
- .TP
- .BR ENOMEM
- Insufficient memory exists to add to the spawn file actions object.
- .P
- It shall not be considered an error for the
- .IR 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
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- operation.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- These functions are part of the Spawn option and need not be provided
- on all implementations.
- .P
- 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
- \fIposix_spawn_file_actions_addclose\fR()
- 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
- .IR exec .
- .SH RATIONALE
- A spawn file actions object may be initialized to contain an ordered
- sequence of
- \fIclose\fR(),
- \fIdup2\fR(),
- and
- \fIopen\fR()
- operations to be used by
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- 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\fR()
- or
- \fIposix_spawnp\fR()
- call. It had been suggested that the
- \fIclose\fR()
- and
- \fIdup2\fR()
- 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\fR()
- or
- \fIposix_spawnp\fR()
- call (and close them after), or by passing pathnames to the spawned
- process (in
- .IR 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:
- .IP " 1." 4
- It is consistent with equivalent POSIX.5 (Ada) functionality.
- .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.
- .IP " 3." 4
- It allows file opens that might otherwise fail or violate file
- ownership/access rights if executed by the parent process.
- .P
- Regarding 2. above, note that the spawn open file action provides to
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- the same capability that the shell redirection operators provide to
- \fIsystem\fR(),
- only without the intervening execution of a shell; for example:
- .sp
- .RS 4
- .nf
- system ("myprog <file1 3<file2");
- .fi
- .P
- .RE
- .P
- 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\fR()
- to occur in the context of the child process after other file
- descriptors have been closed (that must remain open in the parent).
- .P
- 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\fR()
- action during
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- 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"
- .P
- 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\fR()
- or
- \fIposix_spawnp\fR()
- 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.
- .P
- It was noted by a member of the Ada Language Bindings working group
- that the approved Ada Language
- .IR Start_Process
- family of POSIX process primitives use a caller-specified set of file
- actions to alter the normal
- \fIfork\fR()/\c
- .IR 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.
- .P
- The
- \fIposix_spawn_file_actions_addclose\fR()
- 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
- \fIsetrlimit\fR()
- 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
- \fIposix_spawn_file_actions_addclose\fR()
- should return
- .BR [EBADF]
- if
- .IR fildes
- is greater than or equal to
- {OPEN_MAX}.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .ad l
- .IR "\fIclose\fR\^(\|)",
- .IR "\fIdup\fR\^(\|)",
- .IR "\fIopen\fR\^(\|)",
- .IR "\fIposix_spawn\fR\^(\|)",
- .IR "\fIposix_spawn_file_actions_adddup2\fR\^(\|)",
- .IR "\fIposix_spawn_file_actions_destroy\fR\^(\|)"
- .ad b
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<spawn.h>\fP"
- .\"
- .SH COPYRIGHT
- 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 .
- .PP
- 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 .