1.\" $NetBSD: posix_spawn_file_actions_addchdir.3,v 1.3 2021/11/15 16:00:25 kre Exp $ 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.\" Portions of this text are reprinted and reproduced in electronic form 25.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 26.\" Portable Operating System Interface (POSIX), The Open Group Base 27.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 28.\" Electrical and Electronics Engineers, Inc and The Open Group. In the 29.\" event of any discrepancy between this version and the original IEEE and 30.\" The Open Group Standard, the original IEEE and The Open Group Standard is 31.\" the referee document. The original Standard can be obtained online at 32.\" http://www.opengroup.org/unix/online.html. 33.\" 34.Dd July 8, 2020 35.Dt POSIX_SPAWN_FILE_ACTIONS_ADDCHDIR 3 36.Os 37.Sh NAME 38.Nm posix_spawn_file_actions_addchdir , 39.Nm posix_spawn_file_actions_addfchdir 40.Nd add chdir or fchdir action to spawn file actions object 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In spawn.h 45.Ft int 46.Fn posix_spawn_file_actions_addchdir "posix_spawn_file_actions_t *restrict file_actions" "const char *restrict path" 47.Ft int 48.Fn posix_spawn_file_actions_addfchdir "posix_spawn_file_actions_t * file_actions" "int fildes" 49.Sh DESCRIPTION 50The 51.Fn posix_spawn_file_actions_addchdir 52function adds a chdir action to the object referenced by 53.Fa file_actions 54that causes the working directory to be set to 55.Fa path 56(as if 57.Bd -literal -offset indent 58chdir(path) 59.Ed 60.Pp 61had been called) for a new process spawned using this file actions 62object. 63A relative 64.Fa path 65is interpreted relative to the working directory determined by any 66prior actions. 67The string pointed to by 68.Fa path 69is copied by the 70.Fn posix_spawn_file_actions_addchdir 71function. 72.Pp 73The 74.Fn posix_spawn_file_actions_addfchdir 75function adds a fchdir action to the object referenced by 76.Fa file_actions 77that causes the working directory to be set to the directory referenced by 78.Fa fildes 79(as if 80.Bd -literal -offset indent 81fchdir(fildes) 82.Ed 83.Pp 84had been called) for a new process spawned using this file actions object. 85.\" The last paragraph of APPLICATION USAGE 86.Pp 87File actions are performed in the new process created by 88.Fn posix_spawn 89or 90.Fn posix_spawnp 91in the same order that they were added to the file actions object. 92Thus the execution of an 93.Dq open 94action that was created by a call to 95.Fn posix_spawn_file_actions_addopen 96that specifies a relative path will be affected by the execution of a 97chdir or fchdir action that was created by a previous call to 98.Fn posix_spawn_file_actions_addchdir 99or 100.Fn posix_spawn_file_actions_addfchdir . 101Likewise, a relative path passed to 102.Fn posix_spawn 103will be affected by the last chdir or fchdir action in the file action list. 104.Sh RETURN VALUES 105Upon successful completion, these function return zero; 106otherwise, an error number is returned to indicate the error. 107.Sh ERRORS 108The 109.Fn posix_spawn_file_actions_addfchdir 110function fails if: 111.Bl -tag -width Er 112.It Bq Er EBADF 113The value specified by 114.Fa fildes 115is negative. 116.El 117.Pp 118Both functions may fail with: 119.Bl -tag -width Er 120.It Bq Er EINVAL 121The value specified by 122.Fa file_actions 123is invalid. 124.It Bq Er ENOMEM 125Insufficient memory exists to add the spawn file actions object. 126.El 127.Pp 128It is not an error for the 129.Fa path 130or 131.Fa fildes 132argument passed to these functions to specify a pathname or file descriptor 133for which the specified operation could not be performed at the time of the call. 134Any such error will be detected when the associated file actions object is 135later used during a 136.Fn posix_spawn 137or 138.Fn posix_spawnp 139operation. 140.Sh SEE ALSO 141.Xr chdir 2 , 142.Xr fchdir 2 , 143.Xr posix_spawn 3 , 144.Xr posix_spawn_file_actions_destroy 3 , 145.Xr posix_spawn_file_actions_init 3 , 146.Xr posix_spawnp 3 147.Sh STANDARDS 148The 149.Fn posix_spawn_file_actions_addchdir 150and 151.Fn posix_spawn_file_actions_addfchdir 152functions conform to 153.St -p1003.1-2001 . 154.Sh HISTORY 155The POSIX implementation of 156.Fn posix_spawn_file_actions_addchdir 157and 158.Fn posix_spawn_file_actions_addfchdir 159is derived from SOLARIS kernel's 160.Fn posix_spawn_file_actions_addchdir_np . 161.Sh AUTHORS 162.An Piyush Sachdeva 163