git: ee8c31c6dae4 - stable/15 - cred: 'struct ucred': Rework comment on 'cr_gid'/cr_groups[]

The branch stable/15 has been updated by olce:

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

commit ee8c31c6dae4069cb4f2f29bd23c6692882ca652
Author:     Olivier Certner <olce@FreeBSD.org>
AuthorDate: 2025-08-27 14:33:24 +0000
Commit:     Olivier Certner <olce@FreeBSD.org>
CommitDate: 2025-09-23 12:02:42 +0000

    cred: 'struct ucred': Rework comment on 'cr_gid'/cr_groups[]
    
    Make it more straightforward for consumers.  Also, recommend using
    cr_sgroups[] for supplementary groups, as this can generally alleviate
    index problems and will help us spot and change consumers if/when
    'struct ucred' is evolved incompatibly (and cr_sgroups[] suppressed).
    
    MFC after:      5 days
    MFC to:         stable/15
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D52269
    
    (cherry picked from commit 0abeb8d8d8df1842b0c2d2276c958b0150579a1c)
---
 sys/sys/ucred.h | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/sys/sys/ucred.h b/sys/sys/ucred.h
index 9c1d8545af34..254f58841993 100644
--- a/sys/sys/ucred.h
+++ b/sys/sys/ucred.h
@@ -112,15 +112,21 @@ struct xucred {
 	short	cr_ngroups;		/* number of groups (incl. cr_gid). */
 	union {
 		/*
-		 * Special little hack to avoid needing a cr_gid macro, which
-		 * would cause problems if one were to use it with struct ucred
-		 * which also has a cr_groups member.
+		 * The effective GID has been the first element of cr_groups[]
+		 * for historical reasons.  It should be accessed using the
+		 * 'cr_gid' identifier.  Supplementary groups should be accessed
+		 * using cr_sgroups[].  Note that 'cr_ngroups' currently
+		 * includes the effective GID.
+		 *
+		 * XXXOC: On the next API change (requires versioning), please
+		 * replace this union with a true unaliased field 'cr_gid' and
+		 * make sure that cr_groups[]/'cr_ngroups' only account for
+		 * supplementary groups.
 		 */
 		struct {
 			gid_t	cr_gid;		/* effective group id */
 			gid_t	cr_sgroups[XU_NGROUPS - 1];
 		};
-
 		gid_t	cr_groups[XU_NGROUPS];	/* groups */
 	};
 	union {