~ubuntu-branches/ubuntu/precise/manpages-posix/precise

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 

.TH "POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"

.\" posix_spawn_file_actions_addclose 

.SH NAME

posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen

\- add close or open action to spawn file actions

object (\fBADVANCED REALTIME\fP)

.SH SYNOPSIS

.LP

\fB#include <spawn.h>

.br

.sp

int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t *

.br

\ \ \ \ \ \ \fP \fIfile_actions\fP\fB, int\fP \fIfildes\fP\fB);

.br

int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *

.br

\ \ \ \ \ \  restrict\fP \fIfile_actions\fP\fB, int\fP \fIfildes\fP\fB,

.br

\ \ \ \ \ \  const char *restrict\fP \fIpath\fP\fB, int\fP \fIoflag\fP\fB,

mode_t\fP

\fImode\fP\fB); \fP

\fB

.br

\fP

.SH DESCRIPTION

.LP

These functions shall add or delete a close or open action to a spawn

file actions object.

.LP

A spawn file actions object is of type \fBposix_spawn_file_actions_t\fP

(defined in \fI<spawn.h>\fP) and is used to specify a series of actions

to be performed by a \fIposix_spawn\fP() or \fIposix_spawnp\fP()

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

\fBposix_spawn_file_actions_t\fP.

.LP

A spawn file actions object, when passed to \fIposix_spawn\fP() or

\fIposix_spawnp\fP(), 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 \fIposix_spawn\fP() ).

.LP

The \fIposix_spawn_file_actions_addclose\fP() function shall add a

\fIclose\fP action to the object referenced by

\fIfile_actions\fP that shall cause the file descriptor \fIfildes\fP

to be closed (as if \fIclose\fP( \fIfildes\fP) had been

called) when a new process is spawned using this file actions object.

.LP

The \fIposix_spawn_file_actions_addopen\fP() function shall add an

\fIopen\fP action to the object referenced by

\fIfile_actions\fP that shall cause the file named by \fIpath\fP to

be opened (as if \fIopen\fP( \fIpath\fP, \fIoflag\fP,

\fImode\fP) had been called, and the returned file descriptor, if

not \fIfildes\fP, had been changed to \fIfildes\fP) when a new

process is spawned using this file actions object. If \fIfildes\fP

was already an open file descriptor, it shall be closed before

the new file is opened.

.LP

The string described by \fIpath\fP shall be copied by the \fIposix_spawn_file_actions_addopen\fP()

function.

.SH RETURN VALUE

.LP

Upon successful completion, these functions shall return zero; otherwise,

an error number shall be returned to indicate the

error.

.SH ERRORS

.LP

These functions shall fail if:

.TP 7

.B EBADF

The value specified by \fIfildes\fP is negative or greater than or

equal to {OPEN_MAX}.

.sp

.LP

These functions may fail if:

.TP 7

.B EINVAL

The value specified by \fIfile_actions\fP is invalid.

.TP 7

.B ENOMEM

Insufficient memory exists to add to the spawn file actions object.

.sp

.LP

It shall not be considered an error for the \fIfildes\fP 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\fP() or

\fIposix_spawnp\fP() operation.

.LP

\fIThe following sections are informative.\fP

.SH EXAMPLES

.LP

None.

.SH APPLICATION USAGE

.LP

These functions are part of the Spawn option and need not be provided

on all implementations.

.SH RATIONALE

.LP

A spawn file actions object may be initialized to contain an ordered

sequence of \fIclose\fP(), \fIdup2\fP(), and \fIopen\fP() operations

to be used by \fIposix_spawn\fP() or \fIposix_spawnp\fP() 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\fP() or \fIposix_spawnp\fP() call.

It had been suggested that the \fIclose\fP() and \fIdup2\fP() 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\fP()

or \fIposix_spawnp\fP() call (and close them after), or by passing

filenames to the spawned

process (in \fIargv\fP) 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.

.LP

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

.LP

.IP " 3." 4

It allows file opens that might otherwise fail or violate file ownership/access

rights if executed by the parent process.

.LP

.LP

Regarding 2. above, note that the spawn open file action provides

to \fIposix_spawn\fP() and \fIposix_spawnp\fP() the

same capability that the shell redirection operators provide to \fIsystem\fP(),

only

without the intervening execution of a shell; for example:

.sp

.RS

.nf

\fBsystem ("myprog <file1 3<file2");

\fP

.fi

.RE

.LP

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\fP() to occur in the context of the child process

after other file descriptors have been

closed (that must remain open in the parent).

.LP

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\fP() action during

\fIposix_spawn\fP() or \fIposix_spawnp\fP() 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

.LP

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\fP() or \fIposix_spawnp\fP()

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.

.LP

It was noted by a member of the Ada Language Bindings working group

that the approved Ada Language \fIStart_Process\fP family

of POSIX process primitives use a caller-specified set of file actions

to alter the normal \fIfork\fP()/ \fIexec\fP 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.

.SH FUTURE DIRECTIONS

.LP

None.

.SH SEE ALSO

.LP

\fIclose\fP() , \fIdup\fP() , \fIopen\fP() , \fIposix_spawn\fP() ,

\fIposix_spawn_file_actions_adddup2\fP() , \fIposix_spawn_file_actions_destroy\fP()

, \fIposix_spawnp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,

\fI<spawn.h>\fP

.SH COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form

from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology

-- Portable Operating System Interface (POSIX), The Open Group Base

Specifications Issue 6, Copyright (C) 2001-2003 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 .