git: 78963d796d5c - main - Document posix_spawn_file_actions_addclosefrom_np(3)

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=78963d796d5cd8b4f6f0e810eaae7a5f02706b02

commit 78963d796d5cd8b4f6f0e810eaae7a5f02706b02
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2021-11-28 00:23:55 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2021-11-30 01:43:54 +0000

    Document posix_spawn_file_actions_addclosefrom_np(3)
    
    Reviewed by:    kevans, ngie (previous version)
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D33143
---
 lib/libc/gen/Makefile.inc                       |  1 +
 lib/libc/gen/posix_spawn.3                      |  6 ++++++
 lib/libc/gen/posix_spawn_file_actions_addopen.3 | 26 ++++++++++++++++++++-----
 lib/libc/gen/posix_spawn_file_actions_init.3    |  1 +
 4 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc
index 0b53a275e861..6a9e284b5860 100644
--- a/lib/libc/gen/Makefile.inc
+++ b/lib/libc/gen/Makefile.inc
@@ -463,6 +463,7 @@ MLINKS+=modf.3 modff.3 \
 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_addclosefrom_np.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 \
diff --git a/lib/libc/gen/posix_spawn.3 b/lib/libc/gen/posix_spawn.3
index 848733a41a7d..f7d54903dcb6 100644
--- a/lib/libc/gen/posix_spawn.3
+++ b/lib/libc/gen/posix_spawn.3
@@ -422,6 +422,11 @@ in addition to those described by
 This implementation ignores any errors from
 .Fn close ,
 including trying to close a descriptor that is not open.
+The ignore extends to any errors from individual file descriptors
+.Fn close
+executed as part of the
+.Fn closefrom
+action.
 .El
 .Sh SEE ALSO
 .Xr close 2 ,
@@ -434,6 +439,7 @@ including trying to close a descriptor that is not open.
 .Xr setpgid 2 ,
 .Xr vfork 2 ,
 .Xr posix_spawn_file_actions_addclose 3 ,
+.Xr posix_spawn_file_actions_addclosefrom_np 3 ,
 .Xr posix_spawn_file_actions_adddup2 3 ,
 .Xr posix_spawn_file_actions_addopen 3 ,
 .Xr posix_spawn_file_actions_addchdir_np 3 ,
diff --git a/lib/libc/gen/posix_spawn_file_actions_addopen.3 b/lib/libc/gen/posix_spawn_file_actions_addopen.3
index b364e92c18f8..0782e15b3126 100644
--- a/lib/libc/gen/posix_spawn_file_actions_addopen.3
+++ b/lib/libc/gen/posix_spawn_file_actions_addopen.3
@@ -41,9 +41,10 @@
 .Nm posix_spawn_file_actions_addopen ,
 .Nm posix_spawn_file_actions_adddup2 ,
 .Nm posix_spawn_file_actions_addclose ,
+.Nm posix_spawn_file_actions_addclosefrom_np ,
 .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"
+.Nd "add open, dup2, close, closefrom, or chdir/fchdir actions to spawn file actions object"
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -68,6 +69,11 @@
 .Fa "int fildes"
 .Fc
 .Ft int
+.Fo posix_spawn_file_actions_addclosefrom_np
+.Fa "posix_spawn_file_actions_t * file_actions"
+.Fa "int from"
+.Fc
+.Ft int
 .Fo posix_spawn_file_actions_addchdir_np
 .Fa "posix_spawn_file_actions_t *restrict file_actions"
 .Fa "const char *restrict path"
@@ -177,6 +183,14 @@ had been called) when a new process is spawned using this file actions
 object.
 .Pp
 The
+.Fn posix_spawn_file_actions_addclosefrom_np
+function adds a close action to close all file descriptors numerically
+equal or greater then the argument
+.Fa from .
+For each open file descriptor, logically the close action is performed,
+and any possible errors encountered are ignored.
+.Pp
+The
 .Fn posix_spawn_file_actions_addchdir_np
 and
 .Fn posix_spawn_file_actions_addfchdir_np
@@ -238,9 +252,10 @@ is equal to
 A future update of the Standard is expected to require this behavior.
 .Pp
 The
-.Fn posix_spawn_file_actions_addchdir_np
+.Fn posix_spawn_file_actions_addchdir_np ,
+.Fn posix_spawn_file_actions_addfchdir_np ,
 and
-.Fn posix_spawn_file_actions_addfchdir_np
+.Fn posix_spawn_file_actions_addclosefrom_np
 functions are non-standard functions implemented after the similar
 functionality provided by glibc.
 .Sh HISTORY
@@ -252,9 +267,10 @@ and
 functions first appeared in
 .Fx 8.0 .
 The
-.Fn posix_spawn_file_actions_addchdir_np
+.Fn posix_spawn_file_actions_addchdir_np ,
+.Fn posix_spawn_file_actions_addfchdir_np ,
 and
-.Fn posix_spawn_file_actions_addfchdir_np
+.Fn posix_spawn_file_actions_addclosefrom_np
 functions first appeared in
 .Fx 14.0 .
 .Sh AUTHORS
diff --git a/lib/libc/gen/posix_spawn_file_actions_init.3 b/lib/libc/gen/posix_spawn_file_actions_init.3
index 31b62beed570..1215a04f6386 100644
--- a/lib/libc/gen/posix_spawn_file_actions_init.3
+++ b/lib/libc/gen/posix_spawn_file_actions_init.3
@@ -83,6 +83,7 @@ Insufficient memory exists to initialize the spawn file actions object.
 .Sh SEE ALSO
 .Xr posix_spawn 3 ,
 .Xr posix_spawn_file_actions_addclose 3 ,
+.Xr posix_spawn_file_actions_addclosefrom_np 3 ,
 .Xr posix_spawn_file_actions_adddup2 3 ,
 .Xr posix_spawn_file_actions_addopen 3 ,
 .Xr posix_spawnp 3