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