git.saurik.com Git - apple/xnu.git/blob - bsd/man/man3/posix_spawn_file_actions

1 .\"

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] .