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 14.0 . 274.Sh AUTHORS 275.An \&Ed Schouten Aq Mt ed@FreeBSD.org 276