.Dd November 2, 2010

.Os "Mac OS X"

.Nm posix_spawn_file_actions_addclose

.Nm posix_spawn_file_actions_addopen

.Nd add open or close actions to a

.Em posix_spawn_file_actions_t

.Fd #include <spawn.h>

.Ft int

.Fo posix_spawn_file_actions_addclose

.Fa "posix_spawn_file_actions_t *file_actions"

.Fa "int filedes"

.Fc

.Ft int

.Fo posix_spawn_file_actions_addopen

.Fa "posix_spawn_file_actions_t *restrict file_actions"

.Fa "int filedes"

.Fa "const char *restrict path"

.Fa "int oflag"

.Fa "mode_t mode"

.Fc

.Ft int

.Fo posix_spawn_file_actions_adddup2

.Fa "posix_spawn_file_actions_t *file_actions"

.Fa "int filedes"

.Fa "int newfiledes"

.Fc

.Ft int

.Fo posix_spawn_file_actions_addinherit_np

.Fa "posix_spawn_file_actions_t *file_actions"

.Fa "int filedes"

.Fc

.Ft int

.Fo posix_spawn_file_actions_addchdir_np

.Fa "posix_spawn_file_actions_t *file_actions"

.Fa "const char *restrict path"

.Fc

.Ft int

.Fo posix_spawn_file_actions_addfchdir_np

.Fa "posix_spawn_file_actions_t *file_actions"

.Fa "int filedes"

.Fc

The

.Fn posix_spawn_file_actions_addclose

function adds a close operation to the list of operations associated with

the object referenced by

.Em file_actions ,

for subsequent use in a call to

.Xr posix_spawn 2

or

.Xr posix_spawnp 2 .

The descriptor referred to by

.Em filedes

is closed as if

.Fn close

had been called on it prior to the new child process

starting execution.

.Pp

The

.Fn posix_spawn_file_actions_addopen

function adds an open operation to the list of operations associated with

the object referenced by

.Em file_actions ,

for subsequent use in a call to

.Xr posix_spawn 2

or

.Xr posix_spawnp 2 .

The descriptor referred to by

.Em filedes

is opened using the

.Em path ,

.Em oflag ,

and

.Em mode

arguments as if

.Fn open

had been called on it prior to the new child process

starting execution. The string

.Em path

is copied by the

.Fn posix_spawn_file_actions_addopen

function during this process, so storage need not be persistent in the

caller.

.Pp

The

.Fn posix_spawn_file_actions_adddup2

function adds a dup2 operation to the list of operations associated with

the object referenced by

.Em file_actions ,

for subsequent use in a call to

.Xr posix_spawn 2

or

.Xr posix_spawnp 2 .

The descriptor referred to by

.Em newfiledes

is created as if

.Fn dup2

had been called on

.Em filedes

prior to the new child process starting execution.

.Pp

The

.Fn posix_spawn_file_actions_addinherit_np

function adds an abstract inheritance operation to the

list of operations associated with the object referenced by

.Em file_actions ,

for subsequent use in a call to

.Xr posix_spawn 2

or

.Xr posix_spawnp 2 .

The pre-existing descriptor referred to by

.Em filedes

is marked for inheritance into the new process image, and the

.Em FD_CLOEXEC

flag is cleared from the file descriptor in the new process image.

.Pp

Normally, for

.Xr posix_spawn 2

and

.Xr 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

.Em 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

.Xr posix_spawnattr_setflags 3 .

Only file descriptors explicitly manipulated via

.Em file_actions

are made available in the spawned process. In that case,

.Fn 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.

.Pp

The

.Fn posix_spawn_file_actions_addchdir

function adds an chdir operation to the list of operations associated with

the object referenced by

.Em file_actions ,

for subsequent use in a call to

.Xr posix_spawn 2

or

.Xr posix_spawnp 2 .

The current working directory will be set as if

.Fn chdir

had been called with

.Em path

prior to the new child process starting execution.

.Pp

The

.Fn posix_spawn_file_actions_addfchdir

function adds a fchdir operation to the list of operations associated with

the object referenced by

.Em file_actions ,

for subsequent use in a call to

.Xr posix_spawn 2

or

.Xr posix_spawnp 2 .

The current working directory will be set as if

.Fn fchdir

had been called with

.Em filedes

prior to the new child process starting execution.

When

.Em POSIX_SPAWN_CLOEXEC_DEFAULT

is set, the file descriptor

.Em filedes

will not be automatically inherited unless an explicit

.Fn posix_spawn_file_actions_addinherit_np

action for

.Em filedes

has been added.

On success, these functions return 0; on failure they return an error

number from

.In errno.h .

These functions may fail if:

.Bl -tag -width Er

.It Bq Er EBADF

The value specified by

.Fa filedes

is negative or would cause the process to exceed the maximum number of

open files it is allowed.

.It Bq Er EINVAL

The value of

.Fa file_actions

is invalid.

.It Bq Er ENAMETOOLONG

The length of the value specified by

.Fa path

exceeds

.Dv PATH_MAX.

.It Bq Er ENOMEM

Insufficient memory was available to add the new action to

.Fa file_actions .

.El

.Xr posix_spawn 2 ,

.Xr posix_spawnp 2 ,

.Xr posix_spawn_file_actions_init 3 ,

.Xr posix_spawn_file_actions_destroy 3 ,

.Xr posix_spawnattr_setflags 3 .

.St -susv3 [SPN]

The

.Fn posix_spawn_file_actions_init

and

.Fn posix_spawn_file_actions_destroy

function calls appeared in

.St -susv3 [SPN] .