Page MenuHomeFreeBSD
Files F164991210

D52286.id161252.diff
No OneTemporary
Actions

D52286.id161252.diff
View Options

diff --git a/lib/libsys/getgroups.2 b/lib/libsys/getgroups.2
--- 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
+.\" <olce.freebsd@certner.fr> 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 August 29, 2025
.Dt GETGROUPS 2
.Os
.Sh NAME
.Nm getgroups
-.Nd get group access list
+.Nd get the current process' supplementary groups
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
@@ -40,21 +48,15 @@
.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 current 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,
@@ -63,13 +65,23 @@
the calling process without modifying the array pointed to by
.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 actual number of groups placed into
+.Fa gidset
+or, if a value of zero was passed as
+.Fa gidsetlen ,
+the number of groups in the supplementary group set.
+.Pp
A value of -1 indicates that an error occurred, and the error
code is stored in the global variable
.Va errno .
@@ -96,16 +108,41 @@
The
.Fn getgroups
system call conforms to
-.St -p1003.1-2008 .
+.St -p1003.1-2008
+with the additional property that supplementary groups are returned in strictly
+ascending order.
.Sh HISTORY
The
.Fn getgroups
system call appeared in
.Bx 4.2 .
.Pp
+Since
+.Fx 14.3 ,
+the
+.Fn getgroups
+system call has returned the supplementary groups in strictly ascending order.
+.Pp
Before
.Fx 15.0 ,
the
.Fn getgroups
-system call always returned the effective group ID for the process as the first
-element of the array, before the supplementary groups.
+system call would additionally return the process' effective group ID as the
+first element of the array, before the supplementary groups.
+.Sh SECURITY CONSIDERATIONS
+The
+.Fn getgroups
+system call gets the process' supplementary groups 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 .
+.Pp
+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.
+The effective GID is present in the supplementary group list if and only if it
+was explicitly set as a supplementary group.

File Metadata

Mime Type
text/plain
Expires
Thu, Aug 6, 6:13 AM (7 h, 12 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
36087261
Default Alt Text
D52286.id161252.diff (3 KB)

Event Timeline