Page MenuHomeFreeBSD
Differential D52284 Diff 162253 lib/libsys/setgroups.2

Changeset View

Standalone View

View Options

lib/libsys/setgroups.2

.\"-
emasteUnsubmitted
Not Done
Inline Actions

I don't think we need this (.\"-) marker anymore

emaste: I don't think we need this (`.\"-`) marker anymore
.\" SPDX-License-Identifier: BSD-3-Clause
.\"
.\" Copyright (c) 1983, 1991, 1993, 1994 .\" Copyright (c) 1983, 1991, 1993, 1994
.\" The Regents of the University of California. All rights reserved. .\" 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 .\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions .\" modification, are permitted provided that the following conditions
.\" are met: .\" are met:
.\" 1. Redistributions of source code must retain the above copyright .\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer. .\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright .\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the .\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution. .\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors .\" 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 .\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission. .\" without specific prior written permission.
.\" .\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" 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 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE. .\" SUCH DAMAGE.
.\" .\"
.Dd August 1, 2025 .Dd September 17, 2025
.Dt SETGROUPS 2 .Dt SETGROUPS 2
.Os .Os
.Sh NAME .Sh NAME
.Nm setgroups .Nm setgroups
.Nd set group access list .Nd set the calling process' supplementary groups
.Sh LIBRARY .Sh LIBRARY
.Lb libc .Lb libc
.Sh SYNOPSIS .Sh SYNOPSIS
.In sys/param.h .In sys/param.h
.In unistd.h .In unistd.h
.Ft int .Ft int
.Fn setgroups "int ngroups" "const gid_t *gidset" .Fn setgroups "int ngroups" "const gid_t *gidset"
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Fn setgroups .Fn setgroups
system call system call sets the calling process' supplementary groups according to the
sets the supplementary group list of the current user process .Fa gidset
according to the array array.
.Fa gidset .
The The
.Fa ngroups .Fa ngroups
argument argument indicates the number of entries in the array and must be no more than
indicates the number of entries in the array and must be no
more than
.Dv {NGROUPS_MAX} . .Dv {NGROUPS_MAX} .
.Pp
The The
.Fa ngroups .Fa ngroups
argument may be set to 0 to clear the supplementary group list. argument may be set to zero to clear all supplementary groups, in which case
.Fa gidset
is ignored.
.Pp .Pp
Only the super-user may set a new supplementary group list. Only the super-user may install a new supplementary groups set.
.Sh RETURN VALUES .Sh RETURN VALUES
.Rv -std setgroups .Rv -std setgroups
.Sh ERRORS .Sh ERRORS
The The
.Fn setgroups .Fn setgroups
system call will fail if: system call will fail if:
.Bl -tag -width Er .Bl -tag -width Er
.It Bq Er EPERM .It Bq Er EPERM
The caller is not the super-user. The caller is not the super-user.
.It Bq Er EINVAL .It Bq Er EINVAL
The number specified in the The number specified in the
.Fa ngroups .Fa ngroups
argument is larger than the argument is larger than the
.Dv {NGROUPS_MAX}+1 .Dv {NGROUPS_MAX}
limit. limit.
.It Bq Er EFAULT .It Bq Er EFAULT
The address specified for Part of the groups array starting at
.Fa gidset .Fa gidset
is outside the process is outside the process address space.
address space.
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr getgroups 2 , .Xr getgroups 2 ,
.Xr setcred 2 ,
.Xr initgroups 3 .Xr initgroups 3
.Sh HISTORY .Sh HISTORY
The The
.Fn setgroups .Fn setgroups
system call appeared in system call appeared in
.Bx 4.2 . .Bx 4.2 .
.Pp .Pp
Before Before
.Fx 15.0 , .Fx 15.0 ,
the the
.Fn setgroups .Fn setgroups
system call would set the effective group ID for the process to the first system call would set the effective group ID for the process to the first
element of element of
.Fa gidset . .Fa gidset ,
and only the other elements as supplementary groups.
Despite treating the first element as the effective group ID to set, it accepted
an empty
.Fa gidset
.Po
.Fa ngroups
being zero
.Pc
as a stance requiring to drop all supplementary groups, leaving the effective
group ID unchanged.
.Sh SECURITY CONSIDERATIONS
The
.Fn setgroups
system call sets the process' supplementary groups to those contained in the
.Fa gidset
array.
In particular, as evoked in
.Sx HISTORY ,
it does not anymore treat the first element of
.Fa gidset
separately.
Formerly, it would set it as the effective group ID while only the others were
used as supplementary groups.
.Pp
Programs solely relying on
.Fn setgroups
to change the effective group ID must be modified, e.g., to also call
.Xr setegid 2
or to instead use
.Xr setcred 2 ,
else they will unwillingly keep their effective group ID.
.Pp
Programs using
.Fn setgroups
with the effective group ID as the first element of array
.Fa gidset
and not duplicating it in the rest of the array, which includes those using
.Fn initgroups ,
now insert this group ID in the supplementary groups set.
This is in general desirable, as explained in the
.Xr initgroups 3
manual page, and has the consequence that subsequent process' effective group
ID's changes do not remove membership of the original effective group ID, since
these changes do not affect the supplementary groups.
Applications that expressly do not want that must be modified to stop passing
the effective group ID as the first element to
.Fn setgroups .
.Pp
To clear all the calling process' supplementary groups, always use the statement
.Bd -literal -offset indent
setgroups(0, NULL);
.Ed
.Pp
which works also on older FreeBSD version
.Po
see the
.Sx HISTORY
section
.Pc .