git: dbfdd93a188b - stable/14 - getgrouplist.3: Insist on the value returned in 'ngroups'; Minor changes

The branch stable/14 has been updated by olce:

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

commit dbfdd93a188b089b35bee251ad3b60b50fc00117
Author:     Olivier Certner <olce@FreeBSD.org>
AuthorDate: 2025-10-08 10:06:02 +0000
Commit:     Olivier Certner <olce@FreeBSD.org>
CommitDate: 2025-10-10 17:16:02 +0000

    getgrouplist.3: Insist on the value returned in 'ngroups'; Minor changes
    
    Emphasize the peculiar treatment of 'ngroups', through which the
    effective group list's size is returned, even if the passed allocated
    size is not big enough, in which case the output 'groups' array is
    completely filled with the effective group list's first elements.
    
    Use the precise POSIX term for the group associated to the user in the
    password database ("initial numerical group ID"), consistently with what
    was done in initgroups.3.
    
    Use "length" instead of "size" to refer to the number of elements of an
    array (in contrast with its actual size in bytes).
    
    Perform some minor simplifications on top of the last rework.
    
    MFC after:      1 hour
    Sponsored by:   The FreeBSD Foundation
    
    (cherry picked from commit f5544556754ec6b33c1d13c7648a354fef645b2f)
---
 lib/libc/gen/getgrouplist.3 | 33 ++++++++++++++++++++-------------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/lib/libc/gen/getgrouplist.3 b/lib/libc/gen/getgrouplist.3
index 09f01e4fc852..bc7de7678385 100644
--- a/lib/libc/gen/getgrouplist.3
+++ b/lib/libc/gen/getgrouplist.3
@@ -35,7 +35,7 @@
 .\"
 .\"     @(#)getgrouplist.3	8.1 (Berkeley) 6/9/93
 .\"
-.Dd August 29, 2025
+.Dd October 9, 2025
 .Dt GETGROUPLIST 3
 .Os
 .Sh NAME
@@ -50,30 +50,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