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