freebsd/lib/libc/gen/posix_spawn_file_actions_addopen.3

.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
.\" Portable Operating System Interface (POSIX), The Open Group Base
.\" Specifications Issue 6, Copyright (C) 2001-2004 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.
.\"
.Dd May 9, 2013
.Dt POSIX_SPAWN_FILE_ACTIONS_ADDOPEN 3
.Os
.Sh NAME
.Nm posix_spawn_file_actions_addopen ,
.Nm posix_spawn_file_actions_adddup2 ,
.Nm posix_spawn_file_actions_addclose ,
.Nm posix_spawn_file_actions_addclosefrom_np ,
.Nm posix_spawn_file_actions_addchdir_np ,
.Nm posix_spawn_file_actions_addfchdir_np
.Nd "add open, dup2, close, closefrom, or chdir/fchdir actions to spawn file actions object"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In spawn.h
.Ft int
.Fo posix_spawn_file_actions_addopen
.Fa "posix_spawn_file_actions_t * file_actions"
.Fa "int fildes"
.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 fildes"
.Fa "int newfildes"
.Fc
.Ft int
.Fo posix_spawn_file_actions_addclose
.Fa "posix_spawn_file_actions_t * file_actions"
.Fa "int fildes"
.Fc
.Ft int
.Fo posix_spawn_file_actions_addclosefrom_np
.Fa "posix_spawn_file_actions_t * file_actions"
.Fa "int from"
.Fc
.Ft int
.Fo posix_spawn_file_actions_addchdir_np
.Fa "posix_spawn_file_actions_t *restrict 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 fildes"
.Fc
.Sh DESCRIPTION
These functions add an open, dup2 or close action to a spawn
file actions object.
.Pp
A spawn file actions object is of type
.Vt posix_spawn_file_actions_t
(defined in
.In spawn.h )
and is used to specify a series of actions to be performed by a
.Fn posix_spawn
or
.Fn 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.
.Pp
A spawn file actions object, when passed to
.Fn posix_spawn
or
.Fn posix_spawnp ,
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 is 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
.Dv FD_CLOEXEC
flag set is closed (see
.Fn posix_spawn ) .
.Pp
The
.Fn posix_spawn_file_actions_addopen
function adds an open action to the object referenced by
.Fa file_actions
that causes the file named by
.Fa path
to be opened (as if
.Bd -literal -offset indent
open(path, oflag, mode)
.Ed
.Pp
had been called, and the returned file descriptor, if not
.Fa fildes ,
had been changed to
.Fa fildes )
when a new process is spawned using this file actions object.
If
.Fa fildes
was already an open file descriptor, it is closed before the new
file is opened.
.Pp
The string described by
.Fa path
is copied by the
.Fn posix_spawn_file_actions_addopen
function.
.Pp
The
.Fn posix_spawn_file_actions_adddup2
function adds a dup2 action to the object referenced by
.Fa file_actions
that causes the file descriptor
.Fa fildes
to be duplicated as
.Fa newfildes
(as if
.Bd -literal -offset indent
dup2(fildes, newfildes)
.Ed
.Pp
had been called) when a new process is spawned using this file actions object,
except that the
.Dv FD_CLOEXEC
flag for
.Fa newfildes
is cleared even if
.Fa fildes
is equal to
.Fa newfildes .
The difference from
.Fn dup2
is useful for passing a particular file descriptor
to a particular child process.
.Pp
The
.Fn posix_spawn_file_actions_addclose
function adds a close action to the object referenced by
.Fa file_actions
that causes the file descriptor
.Fa fildes
to be closed (as if
.Bd -literal -offset indent
close(fildes)
.Ed
.Pp
had been called) when a new process is spawned using this file actions
object.
.Pp
The
.Fn posix_spawn_file_actions_addclosefrom_np
function adds a close action to close all file descriptors numerically
equal or greater then the argument
.Fa from .
For each open file descriptor, logically the close action is performed,
and any possible errors encountered are ignored.
.Pp
The
.Fn posix_spawn_file_actions_addchdir_np
and
.Fn posix_spawn_file_actions_addfchdir_np
functions add a change current directory action to the object
referenced by
.Fa file_actions
that affects actions (opens with relative path) performed after the operation,
in the order of insertion into the
.Fa file_actions
object.
It also sets the working directory for the spawned program.
The
.Fn posix_spawn_file_actions_addchdir_np
function takes the
.Fa path
to set as the working directory, while
.Fn posix_spawn_file_actions_addfchdir_np
takes the directory file descriptor.
.Sh RETURN VALUES
Upon successful completion, these functions return zero;
otherwise, an error number is returned to indicate the error.
.Sh ERRORS
These
functions fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The value specified by
.Fa fildes
or
.Fa newfildes
is negative.
.It Bq Er ENOMEM
Insufficient memory exists to add to the spawn file actions object.
.El
.Sh SEE ALSO
.Xr close 2 ,
.Xr dup2 2 ,
.Xr open 2 ,
.Xr posix_spawn 3 ,
.Xr posix_spawn_file_actions_destroy 3 ,
.Xr posix_spawn_file_actions_init 3 ,
.Xr posix_spawnp 3
.Sh STANDARDS
The
.Fn posix_spawn_file_actions_addopen ,
.Fn posix_spawn_file_actions_adddup2
and
.Fn posix_spawn_file_actions_addclose
functions conform to
.St -p1003.1-2001 ,
with the exception of the behavior of
.Fn posix_spawn_file_actions_adddup2
if
.Fa fildes
is equal to
.Fa newfildes
(clearing
.Dv FD_CLOEXEC ) .
A future update of the Standard is expected to require this behavior.
.Pp
The
.Fn posix_spawn_file_actions_addchdir_np ,
.Fn posix_spawn_file_actions_addfchdir_np ,
and
.Fn posix_spawn_file_actions_addclosefrom_np
functions are non-standard functions implemented after the similar
functionality provided by glibc.
.Sh HISTORY
The
.Fn posix_spawn_file_actions_addopen ,
.Fn posix_spawn_file_actions_adddup2
and
.Fn posix_spawn_file_actions_addclose
functions first appeared in
.Fx 8.0 .
The
.Fn posix_spawn_file_actions_addchdir_np ,
.Fn posix_spawn_file_actions_addfchdir_np ,
and
.Fn posix_spawn_file_actions_addclosefrom_np
functions first appeared in
.Fx 13.1 .
.Sh AUTHORS
.An \&Ed Schouten Aq Mt ed@FreeBSD.org