]> git.saurik.com Git - apple/xnu.git/blame_incremental - bsd/man/man3/posix_spawn_file_actions_addclose.3
xnu-6153.141.1.tar.gz
[apple/xnu.git] / bsd / man / man3 / posix_spawn_file_actions_addclose.3
... / ...
CommitLineData
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
75The
76.Fn posix_spawn_file_actions_addclose
77function adds a close operation to the list of operations associated with
78the object referenced by
79.Em file_actions ,
80for subsequent use in a call to
81.Xr posix_spawn 2
82or
83.Xr posix_spawnp 2 .
84The descriptor referred to by
85.Em filedes
86is closed as if
87.Fn close
88had been called on it prior to the new child process
89starting execution.
90.Pp
91The
92.Fn posix_spawn_file_actions_addopen
93function adds an open operation to the list of operations associated with
94the object referenced by
95.Em file_actions ,
96for subsequent use in a call to
97.Xr posix_spawn 2
98or
99.Xr posix_spawnp 2 .
100The descriptor referred to by
101.Em filedes
102is opened using the
103.Em path ,
104.Em oflag ,
105and
106.Em mode
107arguments as if
108.Fn open
109had been called on it prior to the new child process
110starting execution. The string
111.Em path
112is copied by the
113.Fn posix_spawn_file_actions_addopen
114function during this process, so storage need not be persistent in the
115caller.
116.Pp
117The
118.Fn posix_spawn_file_actions_adddup2
119function adds a dup2 operation to the list of operations associated with
120the object referenced by
121.Em file_actions ,
122for subsequent use in a call to
123.Xr posix_spawn 2
124or
125.Xr posix_spawnp 2 .
126The descriptor referred to by
127.Em newfiledes
128is created as if
129.Fn dup2
130had been called on
131.Em filedes
132prior to the new child process starting execution.
133.Pp
134The
135.Fn posix_spawn_file_actions_addinherit_np
136function adds an abstract inheritance operation to the
137list of operations associated with the object referenced by
138.Em file_actions ,
139for subsequent use in a call to
140.Xr posix_spawn 2
141or
142.Xr posix_spawnp 2 .
143The pre-existing descriptor referred to by
144.Em filedes
145is marked for inheritance into the new process image, and the
146.Em FD_CLOEXEC
147flag is cleared from the file descriptor in the new process image.
148.Pp
149Normally, for
150.Xr posix_spawn 2
151and
152.Xr posix_spawnp 2 ,
153all file descriptors are inherited from the parent process
154into the spawned process, except for those explicitly
155marked as close-on-exec. However if the flag
156.Em POSIX_SPAWN_CLOEXEC_DEFAULT
157is set, then during the spawn operation, all pre-existing
158file descriptors in the parent process are treated as if they
159had been marked close-on-exec i.e. none of them are automatically
160inherited. See
161.Xr posix_spawnattr_setflags 3 .
162Only file descriptors explicitly manipulated via
163.Em file_actions
164are made available in the spawned process. In that case,
165.Fn posix_spawn_file_actions_addinherit_np
166can be used to make specific pre-existing file
167descriptors from the parent process be
168available in the spawned process.
169.Pp
170The
171.Fn posix_spawn_file_actions_addchdir
172function adds an chdir operation to the list of operations associated with
173the object referenced by
174.Em file_actions ,
175for subsequent use in a call to
176.Xr posix_spawn 2
177or
178.Xr posix_spawnp 2 .
179The current working directory will be set as if
180.Fn chdir
181had been called with
182.Em path
183prior to the new child process starting execution.
184.Pp
185The
186.Fn posix_spawn_file_actions_addfchdir
187function adds a fchdir operation to the list of operations associated with
188the object referenced by
189.Em file_actions ,
190for subsequent use in a call to
191.Xr posix_spawn 2
192or
193.Xr posix_spawnp 2 .
194The current working directory will be set as if
195.Fn fchdir
196had been called with
197.Em filedes
198prior to the new child process starting execution.
199When
200.Em POSIX_SPAWN_CLOEXEC_DEFAULT
201is set, the file descriptor
202.Em filedes
203will not be automatically inherited unless an explicit
204.Fn posix_spawn_file_actions_addinherit_np
205action for
206.Em filedes
207has been added.
208.Sh RETURN VALUES
209On success, these functions return 0; on failure they return an error
210number from
211.In errno.h .
212.Sh ERRORS
213These functions may fail if:
214.Bl -tag -width Er
215.\" ==========
216.It Bq Er EBADF
217The value specified by
218.Fa filedes
219is negative or would cause the process to exceed the maximum number of
220open files it is allowed.
221.\" ==========
222.It Bq Er EINVAL
223The value of
224.Fa file_actions
225is invalid.
226.\" ==========
227.It Bq Er ENAMETOOLONG
228The length of the value specified by
229.Fa path
230exceeds
231.Dv PATH_MAX.
232.\" ==========
233.It Bq Er ENOMEM
234Insufficient 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
246The
247.Fn posix_spawn_file_actions_init
248and
249.Fn posix_spawn_file_actions_destroy
250function calls appeared in
251.St -susv3 [SPN] .