diff options
Diffstat (limited to 'lib/libsys/setgroups.2')
| -rw-r--r-- | lib/libsys/setgroups.2 | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/lib/libsys/setgroups.2 b/lib/libsys/setgroups.2 new file mode 100644 index 000000000000..0ec99507cfb0 --- /dev/null +++ b/lib/libsys/setgroups.2 @@ -0,0 +1,162 @@ +.\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 1983, 1991, 1993, 1994 +.\" 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 September 17, 2025 +.Dt SETGROUPS 2 +.Os +.Sh NAME +.Nm setgroups +.Nd set the calling process' supplementary groups +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In unistd.h +.Ft int +.Fn setgroups "int ngroups" "const gid_t *gidset" +.Sh DESCRIPTION +The +.Fn setgroups +system call sets the calling process' supplementary groups according to the +.Fa gidset +array. +The +.Fa ngroups +argument indicates the number of entries in the array and must be no more than +.Dv {NGROUPS_MAX} . +.Pp +The +.Fa ngroups +argument may be set to zero to clear all supplementary groups, in which case +.Fa gidset +is ignored. +.Pp +Only the super-user may install a new supplementary groups set. +.Sh RETURN VALUES +.Rv -std setgroups +.Sh ERRORS +The +.Fn setgroups +system call will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The caller is not the super-user. +.It Bq Er EINVAL +The number specified in the +.Fa ngroups +argument is larger than the +.Dv {NGROUPS_MAX} +limit. +.It Bq Er EFAULT +Part of the groups array starting at +.Fa gidset +is outside the process address space. +.El +.Sh SEE ALSO +.Xr getgroups 2 , +.Xr setcred 2 , +.Xr initgroups 3 +.Sh HISTORY +The +.Fn setgroups +system call appeared in +.Bx 4.2 . +.Pp +Before +.Fx 15.0 , +the +.Fn setgroups +system call would set the effective group ID for the process to the first +element of +.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 . |