NAME

posix_spawn_file_actions_addclose posix_spawn_file_actions_addopen — add open or close actions to a posix_spawn_file_actions_t

SYNOPSIS

#include <spawn.h>

int
posix_spawn_file_actions_addclose(posix_spawn_file_actions_t *file_actions, int filedes);

int
posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *restrict file_actions, int filedes, const char *restrict path, int oflag, mode_t mode);

int
posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t *file_actions, int filedes, int newfiledes);

int
posix_spawn_file_actions_addinherit_np(posix_spawn_file_actions_t *file_actions, int filedes);

int
posix_spawn_file_actions_addchdir_np(posix_spawn_file_actions_t *file_actions, const char *restrict path);

int
posix_spawn_file_actions_addfchdir_np(posix_spawn_file_actions_t *file_actions, int filedes);

DESCRIPTION

The posix_spawn_file_actions_addclose() function adds a close operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn(2) or posix_spawnp(2). The descriptor referred to by filedes is closed as if close() had been called on it prior to the new child process starting execution.

The posix_spawn_file_actions_addopen() function adds an open operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn(2) or posix_spawnp(2). The descriptor referred to by filedes is opened using the path, oflag, and mode arguments as if open() had been called on it prior to the new child process starting execution. The string path is copied by the posix_spawn_file_actions_addopen() function during this process, so storage need not be persistent in the caller.

The posix_spawn_file_actions_adddup2() function adds a dup2 operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn(2) or posix_spawnp(2). The descriptor referred to by newfiledes is created as if dup2() had been called on filedes prior to the new child process starting execution.

The posix_spawn_file_actions_addinherit_np() function adds an abstract inheritance operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn(2) or posix_spawnp(2). The pre-existing descriptor referred to by filedes is marked for inheritance into the new process image, and the FD_CLOEXEC flag is cleared from the file descriptor in the new process image.

Normally, for posix_spawn(2) and posix_spawnp(2), all file descriptors are inherited from the parent process into the spawned process, except for those explicitly marked as close-on-exec. However if the flag POSIX_SPAWN_CLOEXEC_DEFAULT is set, then during the spawn operation, all pre-existing file descriptors in the parent process are treated as if they had been marked close-on-exec i.e. none of them are automatically inherited. See posix_spawnattr_setflags(3). Only file descriptors explicitly manipulated via file_actions are made available in the spawned process. In that case, posix_spawn_file_actions_addinherit_np() can be used to make specific pre-existing file descriptors from the parent process be available in the spawned process.

The posix_spawn_file_actions_addchdir() function adds an chdir operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn(2) or posix_spawnp(2). The current working directory will be set as if chdir() had been called with path prior to the new child process starting execution.

The posix_spawn_file_actions_addfchdir() function adds a fchdir operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn(2) or posix_spawnp(2). The current working directory will be set as if fchdir() had been called with filedes prior to the new child process starting execution. When POSIX_SPAWN_CLOEXEC_DEFAULT is set, the file descriptor filedes will not be automatically inherited unless an explicit posix_spawn_file_actions_addinherit_np() action for filedes has been added.

RETURN VALUES

On success, these functions return 0; on failure they return an error number from <errno.h>.

ERRORS

These functions may fail if:

[EBADF]

The value specified by filedes is negative or would cause the process to exceed the maximum number of open files it is allowed.

[EINVAL]

The value of file_actions is invalid.

[ENAMETOOLONG]

The length of the value specified by path exceeds PATH_MAX.

[ENOMEM]

Insufficient memory was available to add the new action to file_actions.

SEE ALSO

posix_spawn(2), posix_spawnp(2), posix_spawn_file_actions_init(3), posix_spawn_file_actions_destroy(3), posix_spawnattr_setflags(3).

STANDARDS

Version 3 of the Single UNIX Specification (“SUSv3”) [SPN]

HISTORY

The posix_spawn_file_actions_init() and posix_spawn_file_actions_destroy() function calls appeared in Version 3 of the Single UNIX Specification (“SUSv3”) [SPN].