mirror of
https://git.freebsd.org/src.git
synced 2026-01-16 23:02:24 +00:00
c363dcbe75
In the STANDARDS section, stop mentioning behavior that is not
prescribed by POSIX and make sure to specify which alternative we
implement (as POSIX allows to return or not the effective group ID).
Say more clearly that programs treating specially the first slot of the
returned array must be modified.
Consistently use "group ID" instead of "GID".
These changes are going to be MFCed into stable/14 as part of MFCing
commit 4be38acc82 ("getgroups.2: Clarify, mention ascending order, add
SECURITY CONSIDERATIONS"), so the current commit will be MFCed to
stable/15 only.
MFC after: 1 hour
MFC to: stable/15
Sponsored by: The FreeBSD Foundation
154 lines
4.4 KiB
Groff
154 lines
4.4 KiB
Groff
.\"-
|
|
.\" 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.org> 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
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd October 10, 2025
|
|
.Dt GETGROUPS 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm getgroups
|
|
.Nd get the calling process' supplementary groups
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In unistd.h
|
|
.Ft int
|
|
.Fn getgroups "int gidsetlen" "gid_t *gidset"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn getgroups
|
|
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
|
|
indicates the maximum number of entries that may be placed in
|
|
.Fa gidset .
|
|
.Pp
|
|
If
|
|
.Fa gidsetlen
|
|
is zero,
|
|
.Fn getgroups
|
|
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
|
|
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 .
|
|
.Sh ERRORS
|
|
The possible errors for
|
|
.Fn getgroups
|
|
are:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The argument
|
|
.Fa gidsetlen
|
|
is smaller than the number of supplementary groups
|
|
.Pq but not zero .
|
|
.It Bq Er EFAULT
|
|
An invalid address was encountered while reading from the
|
|
.Fa gidset
|
|
array.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr setgroups 2 ,
|
|
.Xr initgroups 3 ,
|
|
.Xr sysconf 3
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn getgroups
|
|
system call conforms to
|
|
.St -p1003.1-2008 ,
|
|
not reporting the effective group ID.
|
|
.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
|
|
Before
|
|
.Fx 15.0 ,
|
|
the
|
|
.Fn getgroups
|
|
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 group ID in the first slot of
|
|
.Fa gidset .
|
|
Programs that process this slot in a specific way must be modified to obtain the
|
|
effective group ID through other means, such as a call to
|
|
.Xr getegid 2 .
|
|
.Pp
|
|
The effective group ID 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.
|