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