original/man2/getgroups.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
   4 .\"
   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 .\"
  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 2008-06-03 "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 set of supplementary group IDs
 147 is inherited from the parent process, and preserved across an
 148 .BR execve (2).
 149
 150 The maximum number of supplementary group IDs can be found using
 151 .BR sysconf (3):
 152 .nf
 153
 154     long ngroups_max;
 155     ngroups_max = sysconf(_SC_NGROUPS_MAX);
 156
 157 .fi
 158 The maximum return value of
 159 .BR getgroups ()
 160 cannot be larger than one more than this value.
 161 .SH "SEE ALSO"
 162 .BR getgid (2),
 163 .BR setgid (2),
 164 .BR getgrouplist (3),
 165 .BR initgroups (3),
 166 .BR capabilities (7),
 167 .BR credentials (7)