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