lib/libc/gen/posix_spawn_file_actions_addopen.3

   1 .\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" Portions of this text are reprinted and reproduced in electronic form
  26 .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
  27 .\" Portable Operating System Interface (POSIX), The Open Group Base
  28 .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
  29 .\" Electrical and Electronics Engineers, Inc and The Open Group.  In the
  30 .\" event of any discrepancy between this version and the original IEEE and
  31 .\" The Open Group Standard, the original IEEE and The Open Group Standard is
  32 .\" the referee document.  The original Standard can be obtained online at
  33 .\"     http://www.opengroup.org/unix/online.html.
  34 .\"
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd May 9, 2013
  38 .Dt POSIX_SPAWN_FILE_ACTIONS_ADDOPEN 3
  39 .Os
  40 .Sh NAME
  41 .Nm posix_spawn_file_actions_addopen ,
  42 .Nm posix_spawn_file_actions_adddup2 ,
  43 .Nm posix_spawn_file_actions_addclose
  44 .Nd "add open, dup2 or close action to spawn file actions object"
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In spawn.h
  49 .Ft int
  50 .Fn posix_spawn_file_actions_addopen "posix_spawn_file_actions_t * file_actions" "int fildes" "const char *restrict path" "int oflag" "mode_t mode"
  51 .Ft int
  52 .Fn posix_spawn_file_actions_adddup2 "posix_spawn_file_actions_t * file_actions" "int fildes" "int newfildes"
  53 .Ft int
  54 .Fn posix_spawn_file_actions_addclose "posix_spawn_file_actions_t * file_actions" "int fildes"
  55 .Sh DESCRIPTION
  56 These functions add an open, dup2 or close action to a spawn
  57 file actions object.
  58 .Pp
  59 A spawn file actions object is of type
  60 .Vt posix_spawn_file_actions_t
  61 (defined in
  62 .In spawn.h )
  63 and is used to specify a series of actions to be performed by a
  64 .Fn posix_spawn
  65 or
  66 .Fn posix_spawnp
  67 operation in order to arrive at the set of open file descriptors for the
  68 child process given the set of open file descriptors of the parent.
  69 .Pp
  70 A spawn file actions object, when passed to
  71 .Fn posix_spawn
  72 or
  73 .Fn posix_spawnp ,
  74 specify how the set of open file descriptors in the calling
  75 process is transformed into a set of potentially open file descriptors
  76 for the spawned process.
  77 This transformation is as if the specified sequence of actions was
  78 performed exactly once, in the context of the spawned process (prior to
  79 execution of the new process image), in the order in which the actions
  80 were added to the object; additionally, when the new process image is
  81 executed, any file descriptor (from this new set) which has its
  82 .Dv FD_CLOEXEC
  83 flag set is closed (see
  84 .Fn posix_spawn ) .
  85 .Pp
  86 The
  87 .Fn posix_spawn_file_actions_addopen
  88 function adds an open action to the object referenced by
  89 .Fa file_actions
  90 that causes the file named by
  91 .Fa path
  92 to be opened (as if
  93 .Bd -literal -offset indent
  94 open(path, oflag, mode)
  95 .Ed
  96 .Pp
  97 had been called, and the returned file descriptor, if not
  98 .Fa fildes ,
  99 had been changed to
 100 .Fa fildes )
 101 when a new process is spawned using this file actions object.
 102 If
 103 .Fa fildes
 104 was already an open file descriptor, it is closed before the new
 105 file is opened.
 106 .Pp
 107 The string described by
 108 .Fa path
 109 is copied by the
 110 .Fn posix_spawn_file_actions_addopen
 111 function.
 112 .Pp
 113 The
 114 .Fn posix_spawn_file_actions_adddup2
 115 function adds a dup2 action to the object referenced by
 116 .Fa file_actions
 117 that causes the file descriptor
 118 .Fa fildes
 119 to be duplicated as
 120 .Fa newfildes
 121 (as if
 122 .Bd -literal -offset indent
 123 dup2(fildes, newfildes)
 124 .Ed
 125 .Pp
 126 had been called) when a new process is spawned using this file actions object,
 127 except that the
 128 .Dv FD_CLOEXEC
 129 flag for
 130 .Fa newfildes
 131 is cleared even if
 132 .Fa fildes
 133 is equal to
 134 .Fa newfildes .
 135 The difference from
 136 .Fn dup2
 137 is useful for passing a particular file descriptor
 138 to a particular child process.
 139 .Pp
 140 The
 141 .Fn posix_spawn_file_actions_addclose
 142 function adds a close action to the object referenced by
 143 .Fa file_actions
 144 that causes the file descriptor
 145 .Fa fildes
 146 to be closed (as if
 147 .Bd -literal -offset indent
 148 close(fildes)
 149 .Ed
 150 .Pp
 151 had been called) when a new process is spawned using this file actions
 152 object.
 153 .Sh RETURN VALUES
 154 Upon successful completion, these functions return zero;
 155 otherwise, an error number is returned to indicate the error.
 156 .Sh ERRORS
 157 These
 158 functions fail if:
 159 .Bl -tag -width Er
 160 .It Bq Er EBADF
 161 The value specified by
 162 .Fa fildes
 163 or
 164 .Fa newfildes
 165 is negative.
 166 .It Bq Er ENOMEM
 167 Insufficient memory exists to add to the spawn file actions object.
 168 .El
 169 .Sh SEE ALSO
 170 .Xr close 2 ,
 171 .Xr dup2 2 ,
 172 .Xr open 2 ,
 173 .Xr posix_spawn 3 ,
 174 .Xr posix_spawn_file_actions_destroy 3 ,
 175 .Xr posix_spawn_file_actions_init 3 ,
 176 .Xr posix_spawnp 3
 177 .Sh STANDARDS
 178 The
 179 .Fn posix_spawn_file_actions_addopen ,
 180 .Fn posix_spawn_file_actions_adddup2
 181 and
 182 .Fn posix_spawn_file_actions_addclose
 183 functions conform to
 184 .St -p1003.1-2001 ,
 185 with the exception of the behavior of
 186 .Fn posix_spawn_file_actions_adddup2
 187 if
 188 .Fa fildes
 189 is equal to
 190 .Fa newfildes
 191 (clearing
 192 .Dv FD_CLOEXEC ) .
 193 A future update of the Standard is expected to require this behavior,
 194 .Sh HISTORY
 195 The
 196 .Fn posix_spawn_file_actions_addopen ,
 197 .Fn posix_spawn_file_actions_adddup2
 198 and
 199 .Fn posix_spawn_file_actions_addclose
 200 functions first appeared in
 201 .Fx 8.0 .
 202 .Sh AUTHORS
 203 .An Ed Schouten Aq ed@FreeBSD.org