From nobody Wed Sep 17 12:19:20 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4cRd9j0zJTz67HlY; Wed, 17 Sep 2025 12:19:21 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R12" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4cRd9h6HhFz3W7V; Wed, 17 Sep 2025 12:19:20 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1758111560; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=PoIYu/seOYm/edXC8Hv+X4tEgI+BoR5gQY3XBItZRMs=; b=B58xU3mVNIsGw9MLZH4qZdIpbLfayVvJPw+MygoN7UXoVA1LximVuGI6Jwqfo4ghNhmuht IXivK0jwUS6N41mEcu4pYWmE/KdfJ/k9AC5OoYSy80mLrZC4R34MS6ctibWvLb9wmQ9943 n4GII1WHILRzDkdIWTiboV/RGB28NwLsK9wpIVwMgoTNOor2TNs1Brz7sLkeB+J8XmlFGT 7L7XkGV6nzvD3BS9Tqrxu3zy8j8chkcjigEZN3H65J0QxXh1uPH+2Zi6yxuro6bQrt0fXm 1V7Hv8Kosb68y48GaZXUIg2bjmh5F1tc6926YGfyeMH8H8ag25iHr7+s5xefxA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1758111560; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=PoIYu/seOYm/edXC8Hv+X4tEgI+BoR5gQY3XBItZRMs=; b=Sb2wJcGRN0q0pWjwx9wj3NfMPjJfWHpewpasHKw97iHANFYx5tzo6j2xEAD8ktU9BFZjBs Vh8FR1NK8Fe+2tzKc/3ZhTorDmzKcHRmbWqygXzw4su7RyVEBhlSxgPPCBwquzYkgNDHlG 1d3L+JTOBNimwDCgfVr1vvkzagJpQ9k/3/kifIkbgiDYLAeoAAj2zSMbuUSAzSFPUCC75F aasn9D7aHbZcoVJNrejFj+LfeRfdCy65j2ov2uYuNdAvDXsgM10rGypFQ4Wb9dYJMB86uy 6JeO5y3tJjCCl+cpl0zB+EAJ6bMawGNRzykRi1ZetZLg5bvxVR0YmCDRiuTcFg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1758111560; a=rsa-sha256; cv=none; b=fcuno5i8yViXdIXYT3zJomSTLCG1uEQYtBLPCloX9FqCUU2Gb67FoGiOZnJ5zRGFkg0A2C 1DA/P7sCRJmUAiO7OggB/BCKUscRJ+gA18t7+jBPAJ4EzA/hzv9hp9coy84Z91i3IVK9Kb 0wW5Pi/lDf/sVKPXLPzQGNpmrYBhNztbOwz7Qs0CBK5hv0Mgy4+0bediu3adennz4nambj eOpJBFeYm+Jwkz408YSZPrJJBzhTO7+8pPnduVLmIJqbL1N5XRvU+5eJwuQhgm3OGIPSeD n/8t5Bf+oRPuY1MeikHls4BEH580p1+inyDyXt7b4/PiXP3zlGvE8Skm3d1Wtg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4cRd9h5r5Pz9k0; Wed, 17 Sep 2025 12:19:20 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 58HCJKN5086224; Wed, 17 Sep 2025 12:19:20 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 58HCJKhn086221; Wed, 17 Sep 2025 12:19:20 GMT (envelope-from git) Date: Wed, 17 Sep 2025 12:19:20 GMT Message-Id: <202509171219.58HCJKhn086221@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Olivier Certner Subject: git: 4be38acc826f - main - getgroups.2: Clarify, mention ascending order, add SECURITY CONSIDERATIONS List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: olce X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 4be38acc826f260e4c7d3ebbb9de534db449782e Auto-Submitted: auto-generated The branch main has been updated by olce: URL: https://cgit.FreeBSD.org/src/commit/?id=4be38acc826f260e4c7d3ebbb9de534db449782e commit 4be38acc826f260e4c7d3ebbb9de534db449782e Author: Olivier Certner AuthorDate: 2025-08-29 22:43:10 +0000 Commit: Olivier Certner CommitDate: 2025-09-17 12:16:08 +0000 getgroups.2: Clarify, mention ascending order, add SECURITY CONSIDERATIONS Clarify and be more precise about the behavior of getgroups(2), in particular with respect to 'gidsetlen'. Prefer a terminology referring to POSIX terms, i.e., use "supplementary groups" instead of "group access list". Say that getgroups(2) reports the supplementary groups in strictly ascending order and returns the cardinal of the set they form (and mention this has been the case since FreeBSD 14.3). Add a new SECURITY CONSIDERATIONS section contrasting the new behavior after commit 9da2fe96ff2e ("kern: fix setgroups(2) and getgroups(2) to match other platforms") with the historical one. While here, fix some style. Note for MFC to stable/14: The content will have to be revised as the new behavior is not in place. The latter should be mentioned as upcoming in 15. Reviewed by: gbe (older version) MFC after: 5 days Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D52286 --- lib/libsys/getgroups.2 | 94 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 70 insertions(+), 24 deletions(-) diff --git a/lib/libsys/getgroups.2 b/lib/libsys/getgroups.2 index 37c8fbad7215..4881a65d532e 100644 --- a/lib/libsys/getgroups.2 +++ b/lib/libsys/getgroups.2 @@ -1,5 +1,13 @@ +.\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Olivier Certner +.\" at Kumacom SARL under sponsorship from the FreeBSD +.\" Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -25,12 +33,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 1, 2025 +.Dd September 17, 2025 .Dt GETGROUPS 2 .Os .Sh NAME .Nm getgroups -.Nd get group access list +.Nd get the calling process' supplementary groups .Sh LIBRARY .Lb libc .Sh SYNOPSIS @@ -40,36 +48,39 @@ .Sh DESCRIPTION The .Fn getgroups -system call -gets the current supplementary groups of the user process and stores it in the -array -.Fa gidset . -The +system call gets the calling process' supplementary groups and stores them in +the +.Fa gidset +array in strictly ascending order. +The value of .Fa gidsetlen -argument -indicates the number of entries that may be placed in +indicates the maximum number of entries that may be placed in .Fa gidset . -The -.Fn getgroups -system call -returns the actual number of groups returned in -.Fa gidset . -As many as {NGROUPS_MAX} values may be returned. +.Pp If .Fa gidsetlen is zero, .Fn getgroups -returns the number of supplementary group IDs associated with -the calling process without modifying the array pointed to by +returns the cardinal of the calling process' supplementary groups set and +ignores argument .Fa gidset . .Pp +No more than +.Dv {NGROUPS_MAX} +values may ever be returned. The value of .Dv {NGROUPS_MAX} should be obtained using .Xr sysconf 3 to avoid hard-coding it into the executable. .Sh RETURN VALUES -A successful call returns the number of groups in the group set. +On success, the +.Fn getgroups +system call returns the cardinal of the supplementary groups set. +It always succeeds if argument +.Fa gidsetlen +is zero. +.Pp A value of -1 indicates that an error occurred, and the error code is stored in the global variable .Va errno . @@ -81,12 +92,12 @@ are: .It Bq Er EINVAL The argument .Fa gidsetlen -is smaller than the number of groups in the group set. +is smaller than the number of supplementary groups +.Pq but not zero . .It Bq Er EFAULT -The argument +An invalid address was encountered while reading from the .Fa gidset -specifies -an invalid address. +array. .El .Sh SEE ALSO .Xr setgroups 2 , @@ -96,16 +107,51 @@ an invalid address. The .Fn getgroups system call conforms to -.St -p1003.1-2008 . +.St -p1003.1-2008 +with the additional properties that supplementary groups are reported in +strictly ascending order and the returned size coincides with the cardinal of +the set. .Sh HISTORY The .Fn getgroups system call appeared in .Bx 4.2 . .Pp +Since +.Fx 14.3 , +the +.Fn getgroups +system call has treated the supplementary groups as a set, reporting them in +strictly ascending order and returning the cardinal of the set. +.Pp Before .Fx 15.0 , the .Fn getgroups -system call always returned the effective group ID for the process as the first +system call would additionally return the effective group ID as the first element of the array, before the supplementary groups. +.Sh SECURITY CONSIDERATIONS +The +.Fn getgroups +system call gets the supplementary groups set in the +.Fa gidset +array. +In particular, as evoked in +.Sx HISTORY , +it does not anymore retrieve the effective GID in the first slot of +.Fa gidset . +Programs should not make any assumption about which group is placed in the first +slot of +.Fa gidset +other than it being the supplementary group with smallest GID. +.Pp +The effective GID is present in the supplementary groups set if and only if it +was explicitly set as a supplementary group. +The function +.Fn initgroups +enforces that, while the +.Fn setgroups +system call does not. +Please consult the +.Xr initgroups 3 +manual page for the rationale.