bsd/man/man3/posix_spawn_file_actions_addclose.3

   1 .\"
   2 .\" Copyright (c) 2000-2010 Apple Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. The rights granted to you under the License
  10 .\" may not be used to create, or enable the creation or redistribution of,
  11 .\" unlawful or unlicensed copies of an Apple operating system, or to
  12 .\" circumvent, violate, or enable the circumvention or violation of, any
  13 .\" terms of an Apple operating system software license agreement.
  14 .\"
  15 .\" Please obtain a copy of the License at
  16 .\" http://www.opensource.apple.com/apsl/ and read it before using this file.
  17 .\"
  18 .\" The Original Code and all software distributed under the License are
  19 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23 .\" Please see the License for the specific language governing rights and
  24 .\" limitations under the License.
  25 .\"
  26 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27 .\"
  28 .\"     @(#)posix_spawn_file_actions_addclose.3
  29 .
  30 .Dd November 2, 2010
  31 .Dt POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE 3
  32 .Os "Mac OS X"
  33 .Sh NAME
  34 .Nm posix_spawn_file_actions_addclose
  35 .Nm posix_spawn_file_actions_addopen
  36 .Nd add open or close actions to a
  37 .Em posix_spawn_file_actions_t
  38 .Sh SYNOPSIS
  39 .Fd #include <spawn.h>
  40 .Ft int
  41 .Fo posix_spawn_file_actions_addclose
  42 .Fa "posix_spawn_file_actions_t *file_actions"
  43 .Fa "int filedes"
  44 .Fc
  45 .Ft int
  46 .Fo posix_spawn_file_actions_addopen
  47 .Fa "posix_spawn_file_actions_t *restrict file_actions"
  48 .Fa "int filedes"
  49 .Fa "const char *restrict path"
  50 .Fa "int oflag"
  51 .Fa "mode_t mode"
  52 .Fc
  53 .Ft int
  54 .Fo posix_spawn_file_actions_adddup2
  55 .Fa "posix_spawn_file_actions_t *file_actions"
  56 .Fa "int filedes"
  57 .Fa "int newfiledes"
  58 .Fc
  59 .Ft int
  60 .Fo posix_spawn_file_actions_addinherit_np
  61 .Fa "posix_spawn_file_actions_t *file_actions"
  62 .Fa "int filedes"
  63 .Fc
  64 .Ft int
  65 .Fo posix_spawn_file_actions_addchdir_np
  66 .Fa "posix_spawn_file_actions_t *file_actions"
  67 .Fa "const char *restrict path"
  68 .Fc
  69 .Ft int
  70 .Fo posix_spawn_file_actions_addfchdir_np
  71 .Fa "posix_spawn_file_actions_t *file_actions"
  72 .Fa "int filedes"
  73 .Fc
  74 .Sh DESCRIPTION
  75 The
  76 .Fn posix_spawn_file_actions_addclose
  77 function adds a close operation to the list of operations associated with
  78 the object referenced by
  79 .Em file_actions ,
  80 for subsequent use in a call to
  81 .Xr posix_spawn 2
  82 or
  83 .Xr posix_spawnp 2 .
  84 The descriptor referred to by
  85 .Em filedes
  86 is closed as if
  87 .Fn close
  88 had been called on it prior to the new child process
  89 starting execution.
  90 .Pp
  91 The
  92 .Fn posix_spawn_file_actions_addopen
  93 function adds an open operation to the list of operations associated with
  94 the object referenced by
  95 .Em file_actions ,
  96 for subsequent use in a call to
  97 .Xr posix_spawn 2
  98 or
  99 .Xr posix_spawnp 2 .
 100 The descriptor referred to by
 101 .Em filedes
 102 is opened using the
 103 .Em path ,
 104 .Em oflag ,
 105 and
 106 .Em mode
 107 arguments as if
 108 .Fn open
 109 had been called on it prior to the new child process
 110 starting execution.  The string
 111 .Em path
 112 is copied by the
 113 .Fn posix_spawn_file_actions_addopen
 114 function during this process, so storage need not be persistent in the
 115 caller.
 116 .Pp
 117 The
 118 .Fn posix_spawn_file_actions_adddup2
 119 function adds a dup2 operation to the list of operations associated with
 120 the object referenced by
 121 .Em file_actions ,
 122 for subsequent use in a call to
 123 .Xr posix_spawn 2
 124 or
 125 .Xr posix_spawnp 2 .
 126 The descriptor referred to by
 127 .Em newfiledes
 128 is created as if
 129 .Fn dup2
 130 had been called on
 131 .Em filedes
 132 prior to the new child process starting execution.
 133 .Pp
 134 The
 135 .Fn posix_spawn_file_actions_addinherit_np
 136 function adds an abstract inheritance operation to the
 137 list of operations associated with the object referenced by
 138 .Em file_actions ,
 139 for subsequent use in a call to
 140 .Xr posix_spawn 2
 141 or
 142 .Xr posix_spawnp 2 .
 143 The pre-existing descriptor referred to by
 144 .Em filedes
 145 is marked for inheritance into the new process image, and the
 146 .Em FD_CLOEXEC
 147 flag is cleared from the file descriptor in the new process image.
 148 .Pp
 149 Normally, for
 150 .Xr posix_spawn 2
 151 and
 152 .Xr posix_spawnp 2 ,
 153 all file descriptors are inherited from the parent process
 154 into the spawned process, except for those explicitly
 155 marked as close-on-exec.  However if the flag
 156 .Em POSIX_SPAWN_CLOEXEC_DEFAULT
 157 is set, then during the spawn operation, all pre-existing
 158 file descriptors in the parent process are treated as if they
 159 had been marked close-on-exec i.e. none of them are automatically
 160 inherited.  See
 161 .Xr posix_spawnattr_setflags 3 .
 162 Only file descriptors explicitly manipulated via
 163 .Em file_actions
 164 are made available in the spawned process. In that case,
 165 .Fn posix_spawn_file_actions_addinherit_np
 166 can be used to make specific pre-existing file
 167 descriptors from the parent process be
 168 available in the spawned process.
 169 .Pp
 170 The
 171 .Fn posix_spawn_file_actions_addchdir
 172 function adds an chdir operation to the list of operations associated with
 173 the object referenced by
 174 .Em file_actions ,
 175 for subsequent use in a call to
 176 .Xr posix_spawn 2
 177 or
 178 .Xr posix_spawnp 2 .
 179 The current working directory will be set as if
 180 .Fn chdir
 181 had been called with
 182 .Em path
 183 prior to the new child process starting execution.
 184 .Pp
 185 The
 186 .Fn posix_spawn_file_actions_addfchdir
 187 function adds a fchdir operation to the list of operations associated with
 188 the object referenced by
 189 .Em file_actions ,
 190 for subsequent use in a call to
 191 .Xr posix_spawn 2
 192 or
 193 .Xr posix_spawnp 2 .
 194 The current working directory will be set as if
 195 .Fn fchdir
 196 had been called with
 197 .Em filedes
 198 prior to the new child process starting execution.
 199 When
 200 .Em POSIX_SPAWN_CLOEXEC_DEFAULT
 201 is set, the file descriptor
 202 .Em filedes
 203 will not be automatically inherited unless an explicit
 204 .Fn posix_spawn_file_actions_addinherit_np
 205 action for
 206 .Em filedes
 207 has been added.
 208 .Sh RETURN VALUES
 209 On success, these functions return 0; on failure they return an error
 210 number from
 211 .In errno.h .
 212 .Sh ERRORS
 213 These functions may fail if:
 214 .Bl -tag -width Er
 215 .\" ==========
 216 .It Bq Er EBADF
 217 The value specified by
 218 .Fa filedes
 219 is negative or would cause the process to exceed the maximum number of
 220 open files it is allowed.
 221 .\" ==========
 222 .It Bq Er EINVAL
 223 The value of
 224 .Fa file_actions
 225 is invalid.
 226 .\" ==========
 227 .It Bq Er ENAMETOOLONG
 228 The length of the value specified by
 229 .Fa path
 230 exceeds
 231 .Dv PATH_MAX.
 232 .\" ==========
 233 .It Bq Er ENOMEM
 234 Insufficient memory was available to add the new action to
 235 .Fa file_actions .
 236 .El
 237 .Sh SEE ALSO
 238 .Xr posix_spawn 2 ,
 239 .Xr posix_spawnp 2 ,
 240 .Xr posix_spawn_file_actions_init 3 ,
 241 .Xr posix_spawn_file_actions_destroy 3 ,
 242 .Xr posix_spawnattr_setflags 3 .
 243 .Sh STANDARDS
 244 .St -susv3 [SPN]
 245 .Sh HISTORY
 246 The
 247 .Fn posix_spawn_file_actions_init
 248 and
 249 .Fn posix_spawn_file_actions_destroy
 250 function calls appeared in
 251 .St -susv3 [SPN] .