posix_spawn_file_actions_addopen()

Updated: April 19, 2023

Add an “open a file” action to a spawn file action object

Synopsis:

#include <spawn.h>

int posix_spawn_file_actions_addopen(
       posix_spawn_file_actions_t *_Restrict fact_p,
       int new_fd,
       const char *_Restrict path,
       int oflags,
       mode_t omode);

Arguments:

fact_p
A pointer to the spawn file actions object that you want to update. You must have already initialized this object by calling posix_spawn_file_actions_init().
new_fd
The number that you want to use for the new file descriptor.
path
The name of the file to open. The string described by path is copied by the posix_spawn_file_actions_addopen() function.
oflags
Flags that specify the status and access modes of the file.
omode
An object of type mode_t that specifies the access mode to use for a newly created file. For more information, see “Access permissions” in the documentation for stat(), and the description of O_CREAT in the documentation for open().

Library:

libc

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

Description:

The posix_spawn_file_actions_addopen() function adds an open action to the object referenced by fact_p that causes the file named by path to be opened (as if open(path, oflag, mode) had been called, and the returned file descriptor, if not already new_fd, had been changed to new_fd) when a new process is spawned using this file actions object. If new_fd was already an open file descriptor, it will be closed before the new file is opened.

Files that need to be opened for use by the spawned process can alternatively 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.

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");

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 open() to occur in the context of the child process after other file descriptors have 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 (see posix_spawn()), a file created within the parent process will (possibly incorrectly) have the parent's effective user ID as its owner, whereas a file created with an open() action during posix_spawn() or posix_spawnp() will have the parent's real ID as its owner; an open action 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.

Returns:

EOK
Success.
EBADF
The value specified by new_fd is negative or greater than or equal to {OPEN_MAX}.
EINVAL
An argument was invalid, or the value specified by fact_p was invalid.
ENOMEM
Insufficient memory exists to add to the spawn file actions object.

It isn't considered an error if the new_fd argument specifies a file descriptor for which the specified operation couldn't be performed at the time of the call. This type of error isn't detected when the associated file actions object is later used during a posix_spawn() or posix_spawnp() operation.

Classification:

POSIX 1003.1 SPN

Safety:  
Cancellation point No
Interrupt handler Yes
Signal handler Yes
Thread Yes