1.\"- 2.\" SPDX-License-Identifier: BSD-3-Clause 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" Copyright (c) 2025 The FreeBSD Foundation 7.\" 8.\" Portions of this documentation were written by Olivier Certner 9.\" <olce@FreeBSD.org> at Kumacom SARL under sponsorship from the FreeBSD 10.\" Foundation. 11.\" 12.\" Redistribution and use in source and binary forms, with or without 13.\" modification, are permitted provided that the following conditions 14.\" are met: 15.\" 1. Redistributions of source code must retain the above copyright 16.\" notice, this list of conditions and the following disclaimer. 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in the 19.\" documentation and/or other materials provided with the distribution. 20.\" 3. Neither the name of the University nor the names of its contributors 21.\" may be used to endorse or promote products derived from this software 22.\" without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 34.\" SUCH DAMAGE. 35.\" 36.Dd September 17, 2025 37.Dt INITGROUPS 3 38.Os 39.Sh NAME 40.Nm initgroups 41.Nd initialize supplementary groups as per the group database 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In unistd.h 46.Ft int 47.Fn initgroups "const char *name" "gid_t basegid" 48.Sh DESCRIPTION 49The 50.Fn initgroups 51function initializes the current process' supplementary groups as prescribed by 52its arguments and the system's group database. 53.Pp 54It first uses the 55.Fn getgrouplist 56function to compute a list of groups containing the passed 57.Fa basegid , 58which typically is the user's initial numerical group ID from the password 59database, and the supplementary groups in the group database for the user named 60.Fa name . 61It then installs this list as the current process' supplementary groups using 62.Fn setgroups . 63.Sh RETURN VALUES 64.Rv -std initgroups 65.Sh ERRORS 66The 67.Fn initgroups 68function may fail and set 69.Va errno 70to any of the errors specified for the library function 71.Xr setgroups 2 . 72It may also return: 73.Bl -tag -width Er 74.It Bq Er ENOMEM 75The 76.Fn initgroups 77function was unable to allocate temporary storage. 78.El 79.Sh SEE ALSO 80.Xr setgroups 2 , 81.Xr getgrouplist 3 82.Sh HISTORY 83The 84.Fn initgroups 85function appeared in 86.Bx 4.2 . 87.Pp 88The 89.Fn initgroups 90function changed semantics in 91.Fx 15 , 92following that of 93.Xr setgroups 2 94in the same release. 95Before that, it would also set the effective group ID to 96.Fa basegid , 97and would not include the latter in the supplementary groups except before 98.Fx 8 . 99Its current behavior in these respects is known to be compatible with that of 100the following systems up to the specified versions that are current at time of 101this writing: 102.Bl -dash -width "-" -compact 103.It 104Linux (up to 6.6) with the GNU libc (up to 2.42) 105.It 106.Nx 1.1 and greater (up to 10) 107.It 108.Ox (up to 7.7) 109.It 110Systems based on illumos (up to August 2025 sources) 111.El 112.Sh SECURITY CONSIDERATIONS 113As 114.Fa basegid 115is typically the user's initial numerical group ID, to which the current 116process' effective group ID is generally initialized, processes using functions 117to change their effective group ID 118.Pq via Xr setgid 2 or similar 119or that are spawned from executables with the set-group-ID mode bit set will not 120be able to relinquish the access rights deriving from being a member of 121.Fa basegid , 122as these functions do not change the supplementary groups. 123.Pp 124This behavior is generally desirable in order to paper over the difference of 125treatment between the effective group and supplementary ones in this situation, 126as they are all in the end indiscriminately used in traditional UNIX 127discretionary access checks. 128It blends well with the practice of allocating each user its own private group, 129as processes launched from a set-group-ID executable keep the same user and 130consistently stay also in the same user's group. 131Finally, it was also chosen for compatibility with other systems 132.Po 133see the 134.Sx HISTORY 135section 136.Pc . 137.Pp 138This convention of including 139.Fa basegid 140in the supplementary groups is however only enforced by the 141.Fn initgroups 142function, and not by the 143.Xr setgroups 2 144system call, so applications expressly wanting to include in the supplementary 145groups only those specified by the group database can themselves call 146.Fn getgrouplist 147and then 148.Fn setgroups 149on the result with the first element skipped 150.Pq see Xr getgrouplist 3 . 151