posix_spawn_file_actions_addclose()

Add (or delete) a close action to a spawn file actions object

Synopsis:

#include <posix_spawn_file_actions.h>

int posix_spawn_file_actions_addclose(
       posix_spawn_file_actions_t *fact_p,
       int fd);

Arguments:

fact_p

The file action to update the spawn file actions object.

fd

The file descriptors in the array.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

These functions add or delete a close() or open() action to a spawn file actions object. A spawn file actions object is of type posix_spawn_file_actions_t (defined in <spawn.h>) and is used to specify a series of actions to be performed by a posix_spawn() or posix_spawnp()) 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 posix_spawn_file_actions_t.

A spawn file actions object, when passed to posix_spawn() or posix_spawnp(), specifies 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, will be closed (see posix_spawn()). The posix_spawn_file_actions_addclose() function will add a close action to the object referenced by fact_p that causes the file descriptor fd to be closed (as if close(fd) had been called) when a new process is spawned using this file actions object.

A spawn file actions object may be initialized to contain an ordered sequence of close(), dup2(), and open() operations to be used by posix_spawn() or posix_spawnp() 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 posix_spawn() or posix_spawnp() call. It had been suggested that the close() and dup2() 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 posix_spawn() or posix_spawnp() call (and close them after), or by passing filenames to the spawned process (in 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:

1. It is consistent with equivalent POSIX.5 (Ada) functionality. designed to be invoked from a shell.
2. 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.
3. It allows file opens that might otherwise fail or violate file ownership/access rights if executed by the parent process.

Regarding 2. above, note that the spawn open file action provides to posix_spawn() and posix_spawnp() the same capability that the shell redirection operators provide to system(), only without the intervening execution of a shell; for example:

system ("myprog <file1 3<file2");

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 been closed (that must remain open in the parent). 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 open() action during posix_spawn() or posix_spawnp() 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.

File Descriptor Mapping — 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 posix_spawn() or posix_spawnp() 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. It was noted by a member of the Ada Language Bindings working group that the approved Ada Language Start_Process family of POSIX process primitives use a caller-specified set of file actions to alter the normal fork/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.

Returns:

Upon successful completion, these functions returns zero; otherwise, an error number is returned to indicate the error (errno is set).

Errors:

EBADF

The value specified by fd is negative or greater than or equal to {OPEN_MAX}.

EINVAL

For any invalid parameter, or the value specified by fact_p is invalid.

ENOMEM

If the action couldn't be added to the file actions object, or insufficient memory exists to add to the spawn file actions object. It shall not be considered an error for the fd 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 posix_spawn() or posix_spawnp() operation.

EOK

Success.

Classification:

POSIX 1003.1 RTS

See also:

posix_spawnp(), posix_spawn_file_actions_adddup2(), posix_spawn_file_actions_addopen(), posix_spawn_file_actions_destroy(), posix_spawn_file_actions_init(), posix_spawnattr_addpartid(), posix_spawnattr_addpartition(), posix_spawnattr_destroy(), posix_spawnattr_getcred(), posix_spawnattr_getflags(), posix_spawnattr_getnode(), posix_spawnattr_getpartid(), posix_spawnattr_getpgroup(), posix_spawnattr_getrunmask(), posix_spawnattr_getschedparam(), posix_spawnattr_getschedpolicy(), posix_spawnattr_getsigdefault(), posix_spawnattr_getsigignore(), posix_spawnattr_getsigmask(), posix_spawnattr_getstackmax(), posix_spawnattr_getxflags(), posix_spawnattr_init(), posix_spawnattr_setcred(), posix_spawnattr_setflags(), posix_spawnattr_setnode(), posix_spawnattr_setpgroup(), posix_spawnattr_setschedparam(), posix_spawnattr_setrunmask(), posix_spawnattr_setschedpolicy(), posix_spawnattr_setsigdefault(), posix_spawnattr_setsigignore(), posix_spawnattr_setsigmask(), posix_spawnattr_setstackmax(), posix_spawnattr_setxflags(), posix_spawnp()