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 .Dd May 9, 2013
  36 .Dt POSIX_SPAWN_FILE_ACTIONS_ADDOPEN 3
  37 .Os
  38 .Sh NAME
  39 .Nm posix_spawn_file_actions_addopen ,
  40 .Nm posix_spawn_file_actions_adddup2 ,
  41 .Nm posix_spawn_file_actions_addclose ,
  42 .Nm posix_spawn_file_actions_addclosefrom_np ,
  43 .Nm posix_spawn_file_actions_addchdir_np ,
  44 .Nm posix_spawn_file_actions_addfchdir_np
  45 .Nd "add open, dup2, close, closefrom, or chdir/fchdir actions to spawn file actions object"
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In spawn.h
  50 .Ft int
  51 .Fo posix_spawn_file_actions_addopen
  52 .Fa "posix_spawn_file_actions_t * file_actions"
  53 .Fa "int fildes"
  54 .Fa "const char *restrict path"
  55 .Fa "int oflag"
  56 .Fa "mode_t mode"
  57 .Fc
  58 .Ft int
  59 .Fo posix_spawn_file_actions_adddup2
  60 .Fa "posix_spawn_file_actions_t * file_actions"
  61 .Fa "int fildes"
  62 .Fa "int newfildes"
  63 .Fc
  64 .Ft int
  65 .Fo posix_spawn_file_actions_addclose
  66 .Fa "posix_spawn_file_actions_t * file_actions"
  67 .Fa "int fildes"
  68 .Fc
  69 .Ft int
  70 .Fo posix_spawn_file_actions_addclosefrom_np
  71 .Fa "posix_spawn_file_actions_t * file_actions"
  72 .Fa "int from"
  73 .Fc
  74 .Ft int
  75 .Fo posix_spawn_file_actions_addchdir_np
  76 .Fa "posix_spawn_file_actions_t *restrict file_actions"
  77 .Fa "const char *restrict path"
  78 .Fc
  79 .Ft int
  80 .Fo posix_spawn_file_actions_addfchdir_np
  81 .Fa "posix_spawn_file_actions_t * file_actions"
  82 .Fa "int fildes"
  83 .Fc
  84 .Sh DESCRIPTION
  85 These functions add an open, dup2 or close action to a spawn
  86 file actions object.
  87 .Pp
  88 A spawn file actions object is of type
  89 .Vt posix_spawn_file_actions_t
  90 (defined in
  91 .In spawn.h )
  92 and is used to specify a series of actions to be performed by a
  93 .Fn posix_spawn
  94 or
  95 .Fn posix_spawnp
  96 operation in order to arrive at the set of open file descriptors for the
  97 child process given the set of open file descriptors of the parent.
  98 .Pp
  99 A spawn file actions object, when passed to
 100 .Fn posix_spawn
 101 or
 102 .Fn posix_spawnp ,
 103 specify how the set of open file descriptors in the calling
 104 process is transformed into a set of potentially open file descriptors
 105 for the spawned process.
 106 This transformation is as if the specified sequence of actions was
 107 performed exactly once, in the context of the spawned process (prior to
 108 execution of the new process image), in the order in which the actions
 109 were added to the object; additionally, when the new process image is
 110 executed, any file descriptor (from this new set) which has its
 111 .Dv FD_CLOEXEC
 112 flag set is closed (see
 113 .Fn posix_spawn ) .
 114 .Pp
 115 The
 116 .Fn posix_spawn_file_actions_addopen
 117 function adds an open action to the object referenced by
 118 .Fa file_actions
 119 that causes the file named by
 120 .Fa path
 121 to be opened (as if
 122 .Bd -literal -offset indent
 123 open(path, oflag, mode)
 124 .Ed
 125 .Pp
 126 had been called, and the returned file descriptor, if not
 127 .Fa fildes ,
 128 had been changed to
 129 .Fa fildes )
 130 when a new process is spawned using this file actions object.
 131 If
 132 .Fa fildes
 133 was already an open file descriptor, it is closed before the new
 134 file is opened.
 135 .Pp
 136 The string described by
 137 .Fa path
 138 is copied by the
 139 .Fn posix_spawn_file_actions_addopen
 140 function.
 141 .Pp
 142 The
 143 .Fn posix_spawn_file_actions_adddup2
 144 function adds a dup2 action to the object referenced by
 145 .Fa file_actions
 146 that causes the file descriptor
 147 .Fa fildes
 148 to be duplicated as
 149 .Fa newfildes
 150 (as if
 151 .Bd -literal -offset indent
 152 dup2(fildes, newfildes)
 153 .Ed
 154 .Pp
 155 had been called) when a new process is spawned using this file actions object,
 156 except that the
 157 .Dv FD_CLOEXEC
 158 flag for
 159 .Fa newfildes
 160 is cleared even if
 161 .Fa fildes
 162 is equal to
 163 .Fa newfildes .
 164 The difference from
 165 .Fn dup2
 166 is useful for passing a particular file descriptor
 167 to a particular child process.
 168 .Pp
 169 The
 170 .Fn posix_spawn_file_actions_addclose
 171 function adds a close action to the object referenced by
 172 .Fa file_actions
 173 that causes the file descriptor
 174 .Fa fildes
 175 to be closed (as if
 176 .Bd -literal -offset indent
 177 close(fildes)
 178 .Ed
 179 .Pp
 180 had been called) when a new process is spawned using this file actions
 181 object.
 182 .Pp
 183 The
 184 .Fn posix_spawn_file_actions_addclosefrom_np
 185 function adds a close action to close all file descriptors numerically
 186 equal or greater then the argument
 187 .Fa from .
 188 For each open file descriptor, logically the close action is performed,
 189 and any possible errors encountered are ignored.
 190 .Pp
 191 The
 192 .Fn posix_spawn_file_actions_addchdir_np
 193 and
 194 .Fn posix_spawn_file_actions_addfchdir_np
 195 functions add a change current directory action to the object
 196 referenced by
 197 .Fa file_actions
 198 that affects actions (opens with relative path) performed after the operation,
 199 in the order of insertion into the
 200 .Fa file_actions
 201 object.
 202 It also sets the working directory for the spawned program.
 203 The
 204 .Fn posix_spawn_file_actions_addchdir_np
 205 function takes the
 206 .Fa path
 207 to set as the working directory, while
 208 .Fn posix_spawn_file_actions_addfchdir_np
 209 takes the directory file descriptor.
 210 .Sh RETURN VALUES
 211 Upon successful completion, these functions return zero;
 212 otherwise, an error number is returned to indicate the error.
 213 .Sh ERRORS
 214 These
 215 functions fail if:
 216 .Bl -tag -width Er
 217 .It Bq Er EBADF
 218 The value specified by
 219 .Fa fildes
 220 or
 221 .Fa newfildes
 222 is negative.
 223 .It Bq Er ENOMEM
 224 Insufficient memory exists to add to the spawn file actions object.
 225 .El
 226 .Sh SEE ALSO
 227 .Xr close 2 ,
 228 .Xr dup2 2 ,
 229 .Xr open 2 ,
 230 .Xr posix_spawn 3 ,
 231 .Xr posix_spawn_file_actions_destroy 3 ,
 232 .Xr posix_spawn_file_actions_init 3 ,
 233 .Xr posix_spawnp 3
 234 .Sh STANDARDS
 235 The
 236 .Fn posix_spawn_file_actions_addopen ,
 237 .Fn posix_spawn_file_actions_adddup2
 238 and
 239 .Fn posix_spawn_file_actions_addclose
 240 functions conform to
 241 .St -p1003.1-2001 ,
 242 with the exception of the behavior of
 243 .Fn posix_spawn_file_actions_adddup2
 244 if
 245 .Fa fildes
 246 is equal to
 247 .Fa newfildes
 248 (clearing
 249 .Dv FD_CLOEXEC ) .
 250 A future update of the Standard is expected to require this behavior.
 251 .Pp
 252 The
 253 .Fn posix_spawn_file_actions_addchdir_np ,
 254 .Fn posix_spawn_file_actions_addfchdir_np ,
 255 and
 256 .Fn posix_spawn_file_actions_addclosefrom_np
 257 functions are non-standard functions implemented after the similar
 258 functionality provided by glibc.
 259 .Sh HISTORY
 260 The
 261 .Fn posix_spawn_file_actions_addopen ,
 262 .Fn posix_spawn_file_actions_adddup2
 263 and
 264 .Fn posix_spawn_file_actions_addclose
 265 functions first appeared in
 266 .Fx 8.0 .
 267 The
 268 .Fn posix_spawn_file_actions_addchdir_np ,
 269 .Fn posix_spawn_file_actions_addfchdir_np ,
 270 and
 271 .Fn posix_spawn_file_actions_addclosefrom_np
 272 functions first appeared in
 273 .Fx 14.0 .
 274 .Sh AUTHORS
 275 .An \&Ed Schouten Aq Mt ed@FreeBSD.org