original/man2/getgroups.2

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