Document posix_spawn_file_actions_addchdir_np(3)

Reviewed by:	kevans, ngie (previous version)
Sponsored by:	The FreeBSD Foundation
MFC after:	1 week
Differential revision:	https://reviews.freebsd.org/D33143

4 files changed, 53 insertions, 4 deletions

diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc
index 75bc30d70976..0b53a275e861 100644
--- a/lib/libc/gen/Makefile.inc
+++ b/lib/libc/gen/Makefile.inc
@@ -464,6 +464,8 @@ MLINKS+=popen.3 pclose.3
 MLINKS+=posix_spawn.3 posix_spawnp.3 \
 	posix_spawn_file_actions_addopen.3 posix_spawn_file_actions_addclose.3 \
 	posix_spawn_file_actions_addopen.3 posix_spawn_file_actions_adddup2.3 \
+	posix_spawn_file_actions_addopen.3 posix_spawn_file_actions_addchdir_np.3 \
+	posix_spawn_file_actions_addopen.3 posix_spawn_file_actions_addfchdir_np.3 \
 	posix_spawn_file_actions_init.3 posix_spawn_file_actions_destroy.3 \
 	posix_spawnattr_getflags.3 posix_spawnattr_setflags.3 \
 	posix_spawnattr_getpgroup.3 posix_spawnattr_setpgroup.3 \
diff --git a/lib/libc/gen/posix_spawn.3 b/lib/libc/gen/posix_spawn.3
index 12df7dc41875..848733a41a7d 100644
--- a/lib/libc/gen/posix_spawn.3
+++ b/lib/libc/gen/posix_spawn.3
@@ -34,7 +34,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 5, 2016
+.Dd November 28, 2021
 .Dt POSIX_SPAWN 3
 .Os
 .Sh NAME
@@ -436,6 +436,8 @@ including trying to close a descriptor that is not open.
 .Xr posix_spawn_file_actions_addclose 3 ,
 .Xr posix_spawn_file_actions_adddup2 3 ,
 .Xr posix_spawn_file_actions_addopen 3 ,
+.Xr posix_spawn_file_actions_addchdir_np 3 ,
+.Xr posix_spawn_file_actions_addfchdir_np 3 ,
 .Xr posix_spawn_file_actions_destroy 3 ,
 .Xr posix_spawn_file_actions_init 3 ,
 .Xr posix_spawnattr_destroy 3 ,
diff --git a/lib/libc/gen/posix_spawn_file_actions_addopen.3 b/lib/libc/gen/posix_spawn_file_actions_addopen.3
index 5cecb49a614d..b364e92c18f8 100644
--- a/lib/libc/gen/posix_spawn_file_actions_addopen.3
+++ b/lib/libc/gen/posix_spawn_file_actions_addopen.3
@@ -40,8 +40,10 @@
 .Sh NAME
 .Nm posix_spawn_file_actions_addopen ,
 .Nm posix_spawn_file_actions_adddup2 ,
-.Nm posix_spawn_file_actions_addclose
-.Nd "add open, dup2 or close action to spawn file actions object"
+.Nm posix_spawn_file_actions_addclose ,
+.Nm posix_spawn_file_actions_addchdir_np ,
+.Nm posix_spawn_file_actions_addfchdir_np
+.Nd "add open, dup2, close, or chdir/fchdir actions to spawn file actions object"
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -65,6 +67,16 @@
 .Fa "posix_spawn_file_actions_t * file_actions"
 .Fa "int fildes"
 .Fc
+.Ft int
+.Fo posix_spawn_file_actions_addchdir_np
+.Fa "posix_spawn_file_actions_t *restrict file_actions"
+.Fa "const char *restrict path"
+.Fc
+.Ft int
+.Fo posix_spawn_file_actions_addfchdir_np
+.Fa "posix_spawn_file_actions_t * file_actions"
+.Fa "int fildes"
+.Fc
 .Sh DESCRIPTION
 These functions add an open, dup2 or close action to a spawn
 file actions object.
@@ -163,6 +175,26 @@ close(fildes)
 .Pp
 had been called) when a new process is spawned using this file actions
 object.
+.Pp
+The
+.Fn posix_spawn_file_actions_addchdir_np
+and
+.Fn posix_spawn_file_actions_addfchdir_np
+functions add a change current directory action to the object
+referenced by
+.Fa file_actions
+that affects actions (opens with relative path) performed after the operation,
+in the order of insertion into the
+.Fa file_actions
+object.
+It also sets the working directory for the spawned program.
+The
+.Fn posix_spawn_file_actions_addchdir_np
+function takes the
+.Fa path
+to set as the working directory, while
+.Fn posix_spawn_file_actions_addfchdir_np
+takes the directory file descriptor.
 .Sh RETURN VALUES
 Upon successful completion, these functions return zero;
 otherwise, an error number is returned to indicate the error.
@@ -204,6 +236,13 @@ is equal to
 (clearing
 .Dv FD_CLOEXEC ) .
 A future update of the Standard is expected to require this behavior.
+.Pp
+The
+.Fn posix_spawn_file_actions_addchdir_np
+and
+.Fn posix_spawn_file_actions_addfchdir_np
+functions are non-standard functions implemented after the similar
+functionality provided by glibc.
 .Sh HISTORY
 The
 .Fn posix_spawn_file_actions_addopen ,
@@ -212,5 +251,11 @@ and
 .Fn posix_spawn_file_actions_addclose
 functions first appeared in
 .Fx 8.0 .
+The
+.Fn posix_spawn_file_actions_addchdir_np
+and
+.Fn posix_spawn_file_actions_addfchdir_np
+functions first appeared in
+.Fx 14.0 .
 .Sh AUTHORS
 .An \&Ed Schouten Aq Mt ed@FreeBSD.org
diff --git a/lib/libc/gen/posix_spawn_file_actions_init.3 b/lib/libc/gen/posix_spawn_file_actions_init.3
index 380eed769003..31b62beed570 100644
--- a/lib/libc/gen/posix_spawn_file_actions_init.3
+++ b/lib/libc/gen/posix_spawn_file_actions_init.3
@@ -34,7 +34,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 24, 2008
+.Dd November 28, 2021
 .Dt POSIX_SPAWN_FILE_ACTIONS_INIT 3
 .Os
 .Sh NAME