From nobody Fri Oct 10 17:16:27 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 4cjtgv5h8fz6Bcrl; Fri, 10 Oct 2025 17:16:27 +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 4cjtgv2kxsz3gTD; Fri, 10 Oct 2025 17:16:27 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1760116587; 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=W1Kzs3Yklv26UFTWrkb+jR7WSR/7KhVlwp2enCWEzqQ=; b=gehD/Vcb5qY7KkXs7fCEv/iiOgCzhDb7GQ7t4fQEX01/YOaulurwh4j/mqk56tqiBGcssY wyrtKW+rqcrDfj9PH8vOBCTCEwMKhiOzVjgKNnHieNmyv6XYX/kZWQ544MV27RJ4Pyd57v uelKOvKiPJLerIhXyGiLNfkwRYkPXCJbyxETHTs/JHFYXQrFaK6D77pPrAfYg5Be+Z+WiB KT7A/MK2JUVwrmIK8KcKvoRfdoYncRd17FO+K6fBJUnYOsTguh28KBJxRFM3b1Syj7WE55 wOPf8NqV9NKlnLD/GaJZLpC0nd24y9Q9wlX/rGLgNdwyzp4xUODYJa9mMh6e2A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1760116587; 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=W1Kzs3Yklv26UFTWrkb+jR7WSR/7KhVlwp2enCWEzqQ=; b=jtpsY7BDwJrjL46cDh2OgsdAtA1rPOShl/HLr80/LPXaEFKxrMsrV9HLoZJGY95cMrwpOj 6AnOK5fadWUXaji866TzIvbhpQIyS51jncc+IW/9p76Lu6b9y+ePYCilGZyfMxJ60Q/5By IyKyjwljK1os7rc2NK2/ZFykeJNgm4764UXAQAxU3cAgNevr5j/K5k+Fc7YnhEvBwSLq6k E06nbg3QbwiWV9CMSNCy/wFk3XIcc9i6tyzBoq6yQ/RZASRxCXSARKg3ldsVU7ryTnugnK Eq8OBk5+3bkygW2sU8KQnr9NvPNSRYevNGfHQbFe6EQHF3MKRcrvVo4ettJAAg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1760116587; a=rsa-sha256; cv=none; b=X4etLT6wQOFCKxW9903BNWuw1okppzWSsLoGXPtdYHsf4qrNduGbUkkj0ii/UdS6l6FOmI JqvE2nQ78b4ixYAZX4/cVD9eYtjovmD5rdSusLwIeBkhLu1wb0UO/iTAIt+SermBANkQbd 3b80omnlqZFzB/AykY4Bm4Z71vJADvWIAOpr9i73goHQ8znT3tH7MbiKVFspYTTt/ZWz4n gbsU746WJtcIDF/aKdwfF1U1TH78ndv9RjNtjDSVn6cqaHqo0AtUAc+dRH6MSX6EvE7CU1 cpNKX/XVStmvOK21WqRhEwLr3c6RIeM2LUILVXzkqOASjQx9saZT4zeclbnThQ== 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 4cjtgv2BfNz1Br6; Fri, 10 Oct 2025 17:16:27 +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 59AHGR97009420; Fri, 10 Oct 2025 17:16:27 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 59AHGRHu009417; Fri, 10 Oct 2025 17:16:27 GMT (envelope-from git) Date: Fri, 10 Oct 2025 17:16:27 GMT Message-Id: <202510101716.59AHGRHu009417@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Olivier Certner Subject: git: 67cf21e16faf - stable/14 - 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/stable/14 X-Git-Reftype: branch X-Git-Commit: 67cf21e16faf17caa51a53efd4b2fd004dae6821 Auto-Submitted: auto-generated The branch stable/14 has been updated by olce: URL: https://cgit.FreeBSD.org/src/commit/?id=67cf21e16faf17caa51a53efd4b2fd004dae6821 commit 67cf21e16faf17caa51a53efd4b2fd004dae6821 Author: Olivier Certner AuthorDate: 2025-08-29 22:43:10 +0000 Commit: Olivier Certner CommitDate: 2025-10-10 17:15:58 +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 close to POSIX terms, i.e., use "effective groups" instead of "group access list". Say that getgroups(2) reports the supplementary groups in strictly ascending order (and mention this has been the case since FreeBSD 14.3). Add a new SECURITY CONSIDERATIONS section, in particular contrasting FreeBSD 15's behavior with the current one. While here, fix some style. Reviewed by: gbe (older version) Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D52286 (cherry picked from commit 4be38acc826f260e4c7d3ebbb9de534db449782e) As indicated in the original commit message, the manual page was specifically modified as stable/14's getgroups(2) still has the old behavior. The original commit message above was reworked to reflect the actual commit content. --- lib/libc/sys/getgroups.2 | 94 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 71 insertions(+), 23 deletions(-) diff --git a/lib/libc/sys/getgroups.2 b/lib/libc/sys/getgroups.2 index 44dff6b4c08d..de747bb092f6 100644 --- a/lib/libc/sys/getgroups.2 +++ b/lib/libc/sys/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 @@ -27,12 +35,12 @@ .\" .\" @(#)getgroups.2 8.2 (Berkeley) 4/16/94 .\" -.Dd January 21, 2011 +.Dd October 10, 2025 .Dt GETGROUPS 2 .Os .Sh NAME .Nm getgroups -.Nd get group access list +.Nd get the calling process' effective groups .Sh LIBRARY .Lb libc .Sh SYNOPSIS @@ -42,36 +50,44 @@ .Sh DESCRIPTION The .Fn getgroups -system call -gets the current group access list of the user process -and stores it in the array -.Fa gidset . -The +system call retrieves the calling process' effective groups, i.e., the effective +group ID and the supplementary groups, and stores them in the +.Fa gidset +array. +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 . -At least one and as many as {NGROUPS_MAX}+1 values may be returned. +.Pp +If the value of +.Fa gidsetlen +is large enough, the effective group ID is stored in the first slot +.Pq Va gidset[0] +and the supplementary groups in subsequent ones in strictly ascending order. 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 one more than the cardinal of the calling process' supplementary groups +set and ignores argument .Fa gidset . .Pp +No more than +.Dv {NGROUPS_MAX}+1 +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 one more than 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 . @@ -83,12 +99,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 plus one +.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 , @@ -98,9 +114,41 @@ an invalid address. The .Fn getgroups system call conforms to -.St -p1003.1-2008 . +.St -p1003.1-2008 , +returning the effective group ID along with supplementary groups. .Sh HISTORY The .Fn getgroups system call appeared in .Bx 4.2 . +.Pp +Since +.Fx 14.3 , +the +.Fn getgroups +system call has been reporting the supplementary groups in strictly ascending +order. +.Pp +Starting with +.Fx 15 , +the +.Fn getgroups +system call will change semantics. +It will return only the supplementary groups, and not the effective group ID +anymore. +.Sh SECURITY CONSIDERATIONS +On success, the group IDs reported in +.Fa gidset +are unique except that the effective group ID in the first slot may be +duplicated in another slot if it is also included in the supplementary groups. +.Pp +Starting with +.Fx 15 , +the +.Fn getgroups +system call will stop reporting the effective group ID as the first slot of the +.Fa gidset +array. +Programs that process this slot in a specific way will need to be modified to +obtain the effective group ID through other means, such as a call to +.Xr getegid 2 .