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