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 .Sh DESCRIPTION
  65 The
  66 .Fn posix_spawn_file_actions_addclose
  67 function adds a close operation to the list of operations associated with
  68 the object referenced by
  69 .Em file_actions ,
  70 for subsequent use in a call to
  71 .Xr posix_spawn 2
  72 or
  73 .Xr posix_spawnp 2 .
  74 The descriptor referred to by
  75 .Em filedes
  76 is closed as if
  77 .Fn close
  78 had been called on it prior to the new child process
  79 starting execution.
  80 .Pp
  81 The
  82 .Fn posix_spawn_file_actions_addopen
  83 function adds an open operation to the list of operations associated with
  84 the object referenced by
  85 .Em file_actions ,
  86 for subsequent use in a call to
  87 .Xr posix_spawn 2
  88 or
  89 .Xr posix_spawnp 2 .
  90 The descriptor referred to by
  91 .Em filedes
  92 is opened using the
  93 .Em path ,
  94 .Em oflag ,
  95 and
  96 .Em mode
  97 arguments as if
  98 .Fn open
  99 had been called on it prior to the new child process
 100 starting execution.  The string
 101 .Em path
 102 is copied by the
 103 .Fn posix_spawn_file_actions_addopen
 104 function during this process, so storage need not be persistent in the
 105 caller.
 106 .Pp
 107 The
 108 .Fn posix_spawn_file_actions_adddup2
 109 function adds a dup2 operation to the list of operations associated with
 110 the object referenced by
 111 .Em file_actions ,
 112 for subsequent use in a call to
 113 .Xr posix_spawn 2
 114 or
 115 .Xr posix_spawnp 2 .
 116 The descriptor referred to by
 117 .Em newfiledes
 118 is created as if
 119 .Fn dup2
 120 had been called on
 121 .Em filedes
 122 prior to the new child process starting execution.
 123 .Pp
 124 The
 125 .Fn posix_spawn_file_actions_addinherit_np
 126 function adds an abstract inheritance operation to the
 127 list of operations associated with the object referenced by
 128 .Em file_actions ,
 129 for subsequent use in a call to
 130 .Xr posix_spawn 2
 131 or
 132 .Xr posix_spawnp 2 .
 133 The pre-existing descriptor referred to by
 134 .Em filedes
 135 is marked for inheritance into the new process image, and the
 136 .Em FD_CLOEXEC
 137 flag is cleared from the file descriptor in the new process image.
 138 .Pp
 139 Normally, for
 140 .Xr posix_spawn 2
 141 and
 142 .Xr posix_spawnp 2 ,
 143 all file descriptors are inherited from the parent process
 144 into the spawned process, except for those explicitly
 145 marked as close-on-exec.  However if the flag
 146 .Em POSIX_SPAWN_CLOEXEC_DEFAULT
 147 is set, then during the spawn operation, all pre-existing
 148 file descriptors in the parent process are treated as if they
 149 had been marked close-on-exec i.e. none of them are automatically
 150 inherited.  See
 151 .Xr posix_spawnattr_setflags 3 .
 152 Only file descriptors explicitly manipulated via
 153 .Em file_actions
 154 are made available in the spawned process. In that case,
 155 .Fn posix_spawn_file_actions_addinherit_np
 156 can be used to make specific pre-existing file
 157 descriptors from the parent process be
 158 available in the spawned process.
 159 .Sh RETURN VALUES
 160 On success, these functions return 0; on failure they return an error
 161 number from
 162 .In errno.h .
 163 .Sh ERRORS
 164 These functions may fail if:
 165 .Bl -tag -width Er
 166 .\" ==========
 167 .It Bq Er EBADF
 168 The value specified by
 169 .Fa filedes
 170 is negative or would cause the process to exceed the maximum number of
 171 open files it is allowed.
 172 .\" ==========
 173 .It Bq Er EINVAL
 174 The value of
 175 .Fa file_actions
 176 is invalid.
 177 .\" ==========
 178 .It Bq Er ENOMEM
 179 Insufficient memory was available to add the new action to
 180 .Fa file_actions .
 181 .El
 182 .Sh SEE ALSO
 183 .Xr posix_spawn 2 ,
 184 .Xr posix_spawnp 2 ,
 185 .Xr posix_spawn_file_actions_init 3 ,
 186 .Xr posix_spawn_file_actions_destroy 3 ,
 187 .Xr posix_spawnattr_setflags 3 .
 188 .Sh STANDARDS
 189 .St -susv3 [SPN]
 190 .Sh HISTORY
 191 The
 192 .Fn posix_spawn_file_actions_init
 193 and
 194 .Fn posix_spawn_file_actions_destroy
 195 function calls appeared in
 196 .St -susv3 [SPN] .