4 files changed, 153 insertions, 37 deletions
diff --git a/lib/libc/gen/fts.3 b/lib/libc/gen/fts.3
index b937607b48e0..da304e59ee72 100644
--- a/lib/libc/gen/fts.3
+++ b/lib/libc/gen/fts.3
@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd October 1, 2025
+.Dd October 6, 2025
 .Dt FTS 3
 .Os
 .Sh NAME
@@ -69,14 +69,15 @@ on a file hierarchy, which is then supplied to
 the other
 .Nm
 functions.
-The function
+The
 .Fn fts_read
-returns a pointer to a structure describing one of the files in the file
-hierarchy.
-The function
+function returns a pointer to a structure describing one of the files
+in the file hierarchy.
+The
 .Fn fts_children
-returns a pointer to a linked list of structures, each of which describes
-one of the files contained in a directory in the hierarchy.
+function returns a pointer to a linked list of structures, each of
+which describes one of the files contained in a directory in the
+hierarchy.
 In general, directories are visited two distinguishable times; in pre-order
 (before any of their descendants are visited) and in post-order (after all
 of their descendants have been visited).
@@ -544,10 +545,10 @@ from descending into directories that have a different device number
 than the file from which the descent began.
 .El
 .Pp
-The argument
-.Fn compar
-specifies a user-defined function which may be used to order the traversal
-of the hierarchy.
+The
+.Fa compar
+argument points to a user-defined function which may be used to order
+the traversal of the hierarchy.
 It
 takes two pointers to pointers to
 .Vt FTSENT
@@ -625,6 +626,15 @@ structure is returned, and
 .Va errno
 may or may not have been set (see
 .Fa fts_info ) .
+Note that
+.Fn fts_read
+will not set
+.Va errno
+to 0 if called again with the same
+.Fa ftsp
+argument after the
+.Dv FTS_STOP
+flag has been set or the end of the stream has been reached.
 .Pp
 The
 .Vt FTSENT
@@ -639,9 +649,9 @@ directory, in which case they will not be overwritten until after a call to
 .Fn fts_read
 after the
 .Vt FTSENT
-structure has been returned by the function
+structure has been returned by the
 .Fn fts_read
-in post-order.
+function in post-order.
 .Ss Fn fts_children
 The
 .Fn fts_children
@@ -717,10 +727,10 @@ and
 fields.
 .El
 .Ss Fn fts_set
-The function
+The
 .Fn fts_set
-allows the user application to determine further processing for the
-file
+function allows the user application to determine further processing
+for the file
 .Fa f
 of the stream
 .Fa ftsp .
@@ -786,6 +796,39 @@ The file may be one of those most recently returned by either
 or
 .Fn fts_read .
 .El
+.Ss Fn fts_set_clientptr , Fn fts_get_clientptr
+The
+.Fn fts_set_clientptr
+function sets the client data pointer for the stream
+.Fa ftsp
+to
+.Fa clientdata .
+The
+.Fn fts_get_clientptr
+function returns the client data pointer associated with
+.Fa ftsp .
+This can be used to pass per-stream data to the comparison function.
+.Pp
+For performance reasons,
+.Fn fts_get_clientptr
+may be shadowed by a preprocessor macro.
+.Ss Fn fts_get_stream
+The
+.Fn fts_get_stream
+function returns the
+.Nm
+stream associated with the file entry
+.Fa f .
+A typical use for this would be for a comparison function to first call
+.Fn fts_get_stream
+on one of its arguments, then call
+.Fn fts_get_clientptr
+to obtain the client data pointer, which in turn points to information
+necessary to correctly order the two entries.
+.Pp
+For performance reasons,
+.Fn fts_get_stream
+may be shadowed by a preprocessor macro.
 .Ss Fn fts_close
 The
 .Fn fts_close
@@ -797,6 +840,75 @@ or
 .Fn fts_open_b
 was called to open
 .Fa ftsp .
+.Sh RETURN VALUES
+The
+.Fn fts_open
+and
+.Fn fts_open_b
+functions return a pointer to the new
+.Nm
+stream on success and
+.Dv NULL
+on failure.
+.Pp
+The
+.Fn fts_read
+function returns a pointer to the next file entry on success, or if an
+error occurs that relates specifically to that file entry.
+On reaching the end of the file hierarchy, it returns
+.Dv NULL
+and sets the external variable
+.Va errno
+to 0.
+On failure, it returns
+.Dv NULL
+and sets
+.Va errno
+to an appropriate non-zero value.
+If called again after the
+.Dv FTS_STOP
+flag has been set or the end of the stream has been reached,
+.Fn fts_read
+returns
+.Dv NULL
+and leaves
+.Va errno
+untouched.
+.Pp
+The
+.Fn fts_children
+function returns a pointer to a linked list of file entries on
+success.
+On reaching the end of the file hierarchy, it returns
+.Dv NULL
+and sets the external variable
+.Va errno
+to 0.
+On failure, it returns
+.Dv NULL
+and sets
+.Va errno
+to an appropriate non-zero value.
+.Pp
+The
+.Fn fts_set
+function returns 0 on success and \-1 if its
+.Fa instr
+argument is invalid.
+.Pp
+The
+.Fn fts_get_clientptr
+function returns the client data pointer associated with its argument,
+or
+.Dv NULL
+if none has been set.
+.Pp
+The
+.Fn fts_get_stream
+function returns a pointer to the
+.Nm
+stream associated with its argument.
+.Pp
 The
 .Fn fts_close
 function
@@ -853,7 +965,7 @@ functions may fail and set
 as follows:
 .Bl -tag -width Er
 .It Bq Er EINVAL
-The options were invalid, or the list were empty.
+The options were invalid, or the list was empty.
 .El
 .Sh SEE ALSO
 .Xr find 1 ,
diff --git a/lib/libc/gen/fts.c b/lib/libc/gen/fts.c
index cce959ba836a..4aa386d777cd 100644
--- a/lib/libc/gen/fts.c
+++ b/lib/libc/gen/fts.c
@@ -106,7 +106,6 @@ struct _fts_private {
  * This assumption only holds for UFS-like filesystems that implement
  * links and directories this way, so we must punt for others.
  */
-
 static const char *ufslike_filesystems[] = {
 	"ufs",
 	"zfs",
@@ -679,7 +678,6 @@ fts_children(FTS *sp, int instr)
 void *
 (fts_get_clientptr)(FTS *sp)
 {
-
 	return (fts_get_clientptr(sp));
 }
 
@@ -696,7 +694,6 @@ FTS *
 void
 fts_set_clientptr(FTS *sp, void *clientptr)
 {
-
 	sp->fts_clientptr = clientptr;
 }
 
diff --git a/lib/libc/gen/getgrouplist.3 b/lib/libc/gen/getgrouplist.3
index e3939fc2481a..9e05ff7e7a29 100644
--- a/lib/libc/gen/getgrouplist.3
+++ b/lib/libc/gen/getgrouplist.3
@@ -33,7 +33,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd August 29, 2025
+.Dd October 9, 2025
 .Dt GETGROUPLIST 3
 .Os
 .Sh NAME
@@ -48,30 +48,37 @@
 .Sh DESCRIPTION
 The
 .Fn getgrouplist
-function reads through the group database to retrieve the supplementary groups
-for the user specified in
-.Fa name ,
+function retrieves from the group database the supplementary groups for the user
+specified in
+.Fa name
 and returns the effective group list, whose first group is the value of
 .Fa basegid
-and the others are the retrieved supplementary groups.
+and the others are the supplementary groups.
 .Fa basegid
-typically is the user's group number from the password database.
+typically is the user's initial numerical group ID from the password database.
 .Pp
 The effective group list is returned in the array pointed to by
 .Fa groups .
-The caller specifies the size of the
+The caller specifies the length of the
 .Fa groups
 array in the integer pointed to by
-.Fa ngroups ;
-the actual number of groups found is returned in
+.Fa ngroups .
+The number of groups of the effective group list, which may be greater than the
+.Fa groups
+array's length, is returned through
 .Fa ngroups .
 .Sh RETURN VALUES
 The
 .Fn getgrouplist
-function
-returns 0 on success and \-1 if the size of the group list is too small to
-hold all the user's groups.
-Here, the group array will be filled with as many groups as will fit.
+function returns 0 on success and \-1 if the length of the group list is too
+small to hold all the user's groups.
+In the latter case, the
+.Fa groups
+array is filled with as many groups as possible from the start of the effective
+group list, and the length pointed to by
+.Fa ngroups
+is set to the full length of the latter, thus to a value strictly greater than
+before the call.
 .Sh FILES
 .Bl -tag -width /etc/group -compact
 .It Pa /etc/group
diff --git a/lib/libc/gen/initgroups.3 b/lib/libc/gen/initgroups.3
index 4f538fb180ec..74133e7d7048 100644
--- a/lib/libc/gen/initgroups.3
+++ b/lib/libc/gen/initgroups.3
@@ -33,7 +33,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd September 17, 2025
+.Dd October 9, 2025
 .Dt INITGROUPS 3
 .Os
 .Sh NAME
@@ -67,9 +67,9 @@ The
 .Fn initgroups
 function may fail and set
 .Va errno
-to any of the errors specified for the library function
-.Xr setgroups 2 .
-It may also return:
+to any of the errors specified for the
+.Xr setgroups 2
+system call, or to:
 .Bl -tag -width Er
 .It Bq Er ENOMEM
 The