man2/getgroups.2

   1 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
   2 .\" and Copyright (C) 2008, 2010, 2015, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified Thu Oct 31 12:04:29 1996 by Eric S. Raymond <esr@thyrsus.com>
  27 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  28 .\"     Added notes on capability requirements
  29 .\" 2008-05-03, mtk, expanded and rewrote parts of DESCRIPTION and RETURN
  30 .\"     VALUE, made style of page more consistent with man-pages style.
  31 .\"
  32 .TH GETGROUPS 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  33 .SH NAME
  34 getgroups, setgroups \- get/set list of supplementary group IDs
  35 .SH SYNOPSIS
  36 .nf
  37 .B #include <unistd.h>
  38 .PP
  39 .BI "int getgroups(int " size ", gid_t " list []);
  40 .PP
  41 .B #include <grp.h>
  42 .PP
  43 .BI "int setgroups(size_t " size ", const gid_t *" list );
  44 .fi
  45 .PP
  46 .RS -4
  47 Feature Test Macro Requirements for glibc (see
  48 .BR feature_test_macros (7)):
  49 .RE
  50 .PP
  51 .BR setgroups ():
  52 .nf
  53     Since glibc 2.19:
  54         _DEFAULT_SOURCE
  55     Glibc 2.19 and earlier:
  56         _BSD_SOURCE
  57 .fi
  58 .SH DESCRIPTION
  59 .BR getgroups ()
  60 returns the supplementary group IDs of the calling process in
  61 .IR list .
  62 The argument
  63 .I size
  64 should be set to the maximum number of items that can be stored in the
  65 buffer pointed to by
  66 .IR list .
  67 If the calling process is a member of more than
  68 .I size
  69 supplementary groups, then an error results.
  70 .PP
  71 It is unspecified whether the effective group ID of the calling process
  72 is included in the returned list.
  73 (Thus, an application should also call
  74 .BR getegid (2)
  75 and add or remove the resulting value.)
  76 .PP
  77 If
  78 .I size
  79 is zero,
  80 .I list
  81 is not modified, but the total number of supplementary group IDs for the
  82 process is returned.
  83 This allows the caller to determine the size of a dynamically allocated
  84 .I list
  85 to be used in a further call to
  86 .BR getgroups ().
  87 .PP
  88 .BR setgroups ()
  89 sets the supplementary group IDs for the calling process.
  90 Appropriate privileges are required (see the description of the
  91 .BR EPERM
  92 error, below).
  93 The
  94 .I size
  95 argument specifies the number of supplementary group IDs
  96 in the buffer pointed to by
  97 .IR list .
  98 A process can drop all of its supplementary groups with the call:
  99 .PP
 100 .in +4n
 101 .EX
 102 setgroups(0, NULL);
 103 .EE
 104 .in
 105 .SH RETURN VALUE
 106 On success,
 107 .BR getgroups ()
 108 returns the number of supplementary group IDs.
 109 On error, \-1 is returned, and
 110 .I errno
 111 is set to indicate the error.
 112 .PP
 113 On success,
 114 .BR setgroups ()
 115 returns 0.
 116 On error, \-1 is returned, and
 117 .I errno
 118 is set to indicate the error.
 119 .SH ERRORS
 120 .TP
 121 .B EFAULT
 122 .I list
 123 has an invalid address.
 124 .PP
 125 .BR getgroups ()
 126 can additionally fail with the following error:
 127 .TP
 128 .B EINVAL
 129 .I size
 130 is less than the number of supplementary group IDs, but is not zero.
 131 .PP
 132 .BR setgroups ()
 133 can additionally fail with the following errors:
 134 .TP
 135 .B EINVAL
 136 .I size
 137 is greater than
 138 .B NGROUPS_MAX
 139 (32 before Linux 2.6.4; 65536 since Linux 2.6.4).
 140 .TP
 141 .B ENOMEM
 142 Out of memory.
 143 .TP
 144 .B EPERM
 145 The calling process has insufficient privilege
 146 (the caller does not have the
 147 .BR CAP_SETGID
 148 capability in the user namespace in which it resides).
 149 .TP
 150 .BR EPERM " (since Linux 3.19)"
 151 The use of
 152 .BR setgroups ()
 153 is denied in this user namespace.
 154 See the description of
 155 .IR /proc/[pid]/setgroups
 156 in
 157 .BR user_namespaces (7).
 158 .SH CONFORMING TO
 159 .BR getgroups ():
 160 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
 161 .PP
 162 .BR setgroups ():
 163 SVr4, 4.3BSD.
 164 Since
 165 .BR setgroups ()
 166 requires privilege, it is not covered by POSIX.1.
 167 .SH NOTES
 168 A process can have up to
 169 .B NGROUPS_MAX
 170 supplementary group IDs
 171 in addition to the effective group ID.
 172 The constant
 173 .B NGROUPS_MAX
 174 is defined in
 175 .IR <limits.h> .
 176 The set of supplementary group IDs
 177 is inherited from the parent process, and preserved across an
 178 .BR execve (2).
 179 .PP
 180 The maximum number of supplementary group IDs can be found at run time using
 181 .BR sysconf (3):
 182 .PP
 183 .in +4n
 184 .EX
 185 long ngroups_max;
 186 ngroups_max = sysconf(_SC_NGROUPS_MAX);
 187 .EE
 188 .in
 189 .PP
 190 The maximum return value of
 191 .BR getgroups ()
 192 cannot be larger than one more than this value.
 193 Since Linux 2.6.4, the maximum number of supplementary group IDs is also
 194 exposed via the Linux-specific read-only file,
 195 .IR /proc/sys/kernel/ngroups_max .
 196 .PP
 197 The original Linux
 198 .BR getgroups ()
 199 system call supported only 16-bit group IDs.
 200 Subsequently, Linux 2.4 added
 201 .BR getgroups32 (),
 202 supporting 32-bit IDs.
 203 The glibc
 204 .BR getgroups ()
 205 wrapper function transparently deals with the variation across kernel versions.
 206 .\"
 207 .SS C library/kernel differences
 208 At the kernel level, user IDs and group IDs are a per-thread attribute.
 209 However, POSIX requires that all threads in a process
 210 share the same credentials.
 211 The NPTL threading implementation handles the POSIX requirements by
 212 providing wrapper functions for
 213 the various system calls that change process UIDs and GIDs.
 214 These wrapper functions (including the one for
 215 .BR setgroups ())
 216 employ a signal-based technique to ensure
 217 that when one thread changes credentials,
 218 all of the other threads in the process also change their credentials.
 219 For details, see
 220 .BR nptl (7).
 221 .SH SEE ALSO
 222 .BR getgid (2),
 223 .BR setgid (2),
 224 .BR getgrouplist (3),
 225 .BR group_member (3),
 226 .BR initgroups (3),
 227 .BR capabilities (7),
 228 .BR credentials (7)