1*3114379fSRobert Mustacchi.\" 2*3114379fSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3*3114379fSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4*3114379fSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5*3114379fSRobert Mustacchi.\" 1.0 of the CDDL. 6*3114379fSRobert Mustacchi.\" 7*3114379fSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8*3114379fSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9*3114379fSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10*3114379fSRobert Mustacchi.\" 11*3114379fSRobert Mustacchi.\" 12*3114379fSRobert Mustacchi.\" Copyright 2025 Oxide Computer Company 13*3114379fSRobert Mustacchi.\" 14*3114379fSRobert Mustacchi.Dd January 5, 2025 15*3114379fSRobert Mustacchi.Dt POSIX_SPAWN_FILE_ACTIONS_ADDCHDIR 3C 16*3114379fSRobert Mustacchi.Os 17*3114379fSRobert Mustacchi.Sh NAME 18*3114379fSRobert Mustacchi.Nm posix_spawn_file_actions_addchdir , 19*3114379fSRobert Mustacchi.Nm posix_spawn_file_actions_addfchdir 20*3114379fSRobert Mustacchi.Nd add directory changing actions to a spawn file actions object 21*3114379fSRobert Mustacchi.Sh LIBRARY 22*3114379fSRobert Mustacchi.Lb libc 23*3114379fSRobert Mustacchi.Sh SYNOPSIS 24*3114379fSRobert Mustacchi.In spawn.h 25*3114379fSRobert Mustacchi.Ft int 26*3114379fSRobert Mustacchi.Fo posix_spawn_file_actions_addchdir 27*3114379fSRobert Mustacchi.Fa "posix_spawn_file_actions_t *restrict file_actions" 28*3114379fSRobert Mustacchi.Fa "const char *restrict path" 29*3114379fSRobert Mustacchi.Fc 30*3114379fSRobert Mustacchi.Ft int 31*3114379fSRobert Mustacchi.Fo posix_spawn_file_actions_addfchdir 32*3114379fSRobert Mustacchi.Fa "posix_spawn_file_actions_t *restrict file_actions" 33*3114379fSRobert Mustacchi.Fa "int fd" 34*3114379fSRobert Mustacchi.Fc 35*3114379fSRobert Mustacchi.Sh DESCRIPTION 36*3114379fSRobert MustacchiThe 37*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addchdir 38*3114379fSRobert Mustacchiand 39*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addfchdir 40*3114379fSRobert Mustacchifunctions add an action to change the spawned process's current working 41*3114379fSRobert Mustacchidirectory to the spawn file actions object, 42*3114379fSRobert Mustacchi.Fa file_actions . 43*3114379fSRobert MustacchiThe 44*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addchdir 45*3114379fSRobert Mustacchifunction will cause the spawned process to call 46*3114379fSRobert Mustacchi.Xr chdir 2 47*3114379fSRobert Mustacchion 48*3114379fSRobert Mustacchi.Fa path , 49*3114379fSRobert Mustacchiwhile the 50*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addfchdir 51*3114379fSRobert Mustacchifunction will cause the spawned process to call 52*3114379fSRobert Mustacchi.Xr fchdir 2 53*3114379fSRobert Mustacchion 54*3114379fSRobert Mustacchi.Fa fd . 55*3114379fSRobert Mustacchi.Pp 56*3114379fSRobert MustacchiActions are resolved in the order that they are added. 57*3114379fSRobert MustacchiThis implies that if 58*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addchdir 59*3114379fSRobert Mustacchiis called with a relative path, it will be evaluated based on any other 60*3114379fSRobert Mustacchiactions that the process has already taken. 61*3114379fSRobert MustacchiSimilarly, if the 62*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addfchdir 63*3114379fSRobert Mustacchifunction is passed a file descriptor that a prior action has closed 64*3114379fSRobert Mustacchi.Pq Xr posix_spawn_file_actions_addclose 3C , 65*3114379fSRobert Mustacchiopened over 66*3114379fSRobert Mustacchi.Pq Xr posix_spawn_file_actions_addopen 3C , 67*3114379fSRobert Mustacchior 68*3114379fSRobert Mustacchiduplicated over 69*3114379fSRobert Mustacchi.Pq Xr posix_spawn_file_actions_adddup2 3C , 70*3114379fSRobert Mustacchithen the 71*3114379fSRobert Mustacchi.Xr fchdir 2 72*3114379fSRobert Mustacchicall will use the new file descriptor. 73*3114379fSRobert MustacchiThis may cause the call to fail, because 74*3114379fSRobert Mustacchi.Fa fd 75*3114379fSRobert Mustacchino longer refers to a directory, or cause the process to change to a 76*3114379fSRobert Mustacchidifferent directory than originally expected. 77*3114379fSRobert Mustacchi.Pp 78*3114379fSRobert MustacchiThe 79*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addchdir 80*3114379fSRobert Mustacchifunction will duplicate the string 81*3114379fSRobert Mustacchi.Fa path , 82*3114379fSRobert Mustacchiallowing the caller to release any storage associated with it following 83*3114379fSRobert Mustacchithe function returning. 84*3114379fSRobert MustacchiIt does not need to be persisted. 85*3114379fSRobert Mustacchi.Sh RETURN VALUES 86*3114379fSRobert MustacchiUpon successful completion, the 87*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addchdir 88*3114379fSRobert Mustacchiand 89*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addfchdir 90*3114379fSRobert Mustacchifunctions return 91*3114379fSRobert Mustacchi.Sy 0 92*3114379fSRobert Mustacchiand record the corresponding file action. 93*3114379fSRobert MustacchiOtherwise, an error number will be returned. 94*3114379fSRobert Mustacchi.Sh ERRORS 95*3114379fSRobert MustacchiThe 96*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addchdir 97*3114379fSRobert Mustacchiand 98*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addfchdir 99*3114379fSRobert Mustacchifunctions will fail if: 100*3114379fSRobert Mustacchi.Bl -tag -width Er 101*3114379fSRobert Mustacchi.It Er ENOMEM 102*3114379fSRobert MustacchiInsufficient memory exists to add the spawn file actions object. 103*3114379fSRobert Mustacchi.El 104*3114379fSRobert Mustacchi.Pp 105*3114379fSRobert MustacchiAdditionally, the 106*3114379fSRobert Mustacchi.Fn posix_spawn_file_actions_addfchdir 107*3114379fSRobert Mustacchifunction will fail if: 108*3114379fSRobert Mustacchi.Bl -tag -width Er 109*3114379fSRobert Mustacchi.It Er EBADF 110*3114379fSRobert MustacchiThe file descriptor, 111*3114379fSRobert Mustacchi.Fa fd , 112*3114379fSRobert Mustacchiis negative or an otherwise invalid file descriptor. 113*3114379fSRobert Mustacchi.El 114*3114379fSRobert Mustacchi.Sh INTERFACE STABILITY 115*3114379fSRobert Mustacchi.Sy Committed 116*3114379fSRobert Mustacchi.Sh MT-LEVEL 117*3114379fSRobert Mustacchi.Sy MT-Safe 118*3114379fSRobert Mustacchi.Sh SEE ALSO 119*3114379fSRobert Mustacchi.Xr chdir 2 , 120*3114379fSRobert Mustacchi.Xr fchdir 2 , 121*3114379fSRobert Mustacchi.Xr posix_spawn 3C , 122*3114379fSRobert Mustacchi.Xr posix_spawn_file_actions_addclose 3C , 123*3114379fSRobert Mustacchi.Xr posix_spawn_file_actions_adddup 3C , 124*3114379fSRobert Mustacchi.Xr posix_spawn_file_actions_addopen 3C , 125*3114379fSRobert Mustacchi.Xr posix_spawn_file_actions_init 3C 126