man3/getgrouplist.3

   1 .\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk
   2 .\" <mtk.manpages@gmail.com>
   3 .\"
   4 .\" A few pieces remain from an earlier version written in
   5 .\" 2002 by Walter Harms (walter.harms@informatik.uni-oldenburg.de)
   6 .\"
   7 .\" %%%LICENSE_START(VERBATIM)
   8 .\" Permission is granted to make and distribute verbatim copies of this
   9 .\" manual provided the copyright notice and this permission notice are
  10 .\" preserved on all copies.
  11 .\"
  12 .\" Permission is granted to copy and distribute modified versions of this
  13 .\" manual under the conditions for verbatim copying, provided that the
  14 .\" entire resulting derived work is distributed under the terms of a
  15 .\" permission notice identical to this one.
  16 .\"
  17 .\" Since the Linux kernel and libraries are constantly changing, this
  18 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  19 .\" responsibility for errors or omissions, or for damages resulting from
  20 .\" the use of the information contained herein.  The author(s) may not
  21 .\" have taken the same level of care in the production of this manual,
  22 .\" which is licensed free of charge, as they might when working
  23 .\" professionally.
  24 .\"
  25 .\" Formatted or processed versions of this manual, if unaccompanied by
  26 .\" the source, must acknowledge the copyright and authors of this work.
  27 .\" %%%LICENSE_END
  28 .\"
  29 .TH GETGROUPLIST 3 2021-03-22 "GNU" "Linux Programmer's Manual"
  30 .SH NAME
  31 getgrouplist \- get list of groups to which a user belongs
  32 .SH SYNOPSIS
  33 .nf
  34 .B #include <grp.h>
  35 .PP
  36 .BI "int getgrouplist(const char *" user ", gid_t " group ,
  37 .BI "                 gid_t *" groups ", int *" ngroups );
  38 .fi
  39 .PP
  40 .RS -4
  41 Feature Test Macro Requirements for glibc (see
  42 .BR feature_test_macros (7)):
  43 .RE
  44 .PP
  45 .BR getgrouplist ():
  46 .nf
  47     Since glibc 2.19:
  48         _DEFAULT_SOURCE
  49     Glibc 2.19 and earlier:
  50         _BSD_SOURCE
  51 .fi
  52 .SH DESCRIPTION
  53 The
  54 .BR getgrouplist ()
  55 function scans the group database (see
  56 .BR group (5))
  57 to obtain the list of groups that
  58 .I user
  59 belongs to.
  60 Up to
  61 .I *ngroups
  62 of these groups are returned in the array
  63 .IR groups .
  64 .PP
  65 If it was not among the groups defined for
  66 .I user
  67 in the group database, then
  68 .I group
  69 is included in the list of groups returned by
  70 .BR getgrouplist ();
  71 typically this argument is specified as the group ID from
  72 the password record for
  73 .IR user .
  74 .PP
  75 The
  76 .I ngroups
  77 argument is a value-result argument:
  78 on return it always contains the number of groups found for
  79 .IR user ,
  80 including
  81 .IR group ;
  82 this value may be greater than the number of groups stored in
  83 .IR groups .
  84 .SH RETURN VALUE
  85 If the number of groups of which
  86 .I user
  87 is a member is less than or equal to
  88 .IR *ngroups ,
  89 then the value
  90 .I *ngroups
  91 is returned.
  92 .PP
  93 If the user is a member of more than
  94 .I *ngroups
  95 groups, then
  96 .BR getgrouplist ()
  97 returns \-1.
  98 In this case, the value returned in
  99 .IR *ngroups
 100 can be used to resize the buffer passed to a further call
 101 .BR getgrouplist ().
 102 .SH VERSIONS
 103 This function is present since glibc 2.2.4.
 104 .SH ATTRIBUTES
 105 For an explanation of the terms used in this section, see
 106 .BR attributes (7).
 107 .ad l
 108 .nh
 109 .TS
 110 allbox;
 111 lbx lb lb
 112 l l l.
 113 Interface       Attribute       Value
 114 T{
 115 .BR getgrouplist ()
 116 T}      Thread safety   MT-Safe locale
 117 .TE
 118 .hy
 119 .ad
 120 .sp 1
 121 .SH CONFORMING TO
 122 This function is nonstandard; it appears on most BSDs.
 123 .SH BUGS
 124 In glibc versions before 2.3.3,
 125 the implementation of this function contains a buffer-overrun bug:
 126 it returns the complete list of groups for
 127 .IR user
 128 in the array
 129 .IR groups ,
 130 even when the number of groups exceeds
 131 .IR *ngroups .
 132 .SH EXAMPLES
 133 The program below displays the group list for the user named in its
 134 first command-line argument.
 135 The second command-line argument specifies the
 136 .I ngroups
 137 value to be supplied to
 138 .BR getgrouplist ().
 139 The following shell session shows examples of the use of this program:
 140 .PP
 141 .in +4n
 142 .EX
 143 .RB "$" " ./a.out cecilia 0"
 144 getgrouplist() returned \-1; ngroups = 3
 145 .RB "$" " ./a.out cecilia 3"
 146 ngroups = 3
 147 16 (dialout)
 148 33 (video)
 149 100 (users)
 150 .EE
 151 .in
 152 .SS Program source
 153 \&
 154 .EX
 155 #include <stdio.h>
 156 #include <stdlib.h>
 157 #include <grp.h>
 158 #include <pwd.h>
 159
 160 int
 161 main(int argc, char *argv[])
 162 {
 163     int ngroups;
 164     struct passwd *pw;
 165     struct group *gr;
 166
 167     if (argc != 3) {
 168         fprintf(stderr, "Usage: %s <user> <ngroups>\en", argv[0]);
 169         exit(EXIT_FAILURE);
 170     }
 171
 172     ngroups = atoi(argv[2]);
 173
 174     gid_t *groups = malloc(sizeof(*groups) * ngroups);
 175     if (groups == NULL) {
 176         perror("malloc");
 177         exit(EXIT_FAILURE);
 178     }
 179
 180     /* Fetch passwd structure (contains first group ID for user). */
 181
 182     pw = getpwnam(argv[1]);
 183     if (pw == NULL) {
 184         perror("getpwnam");
 185         exit(EXIT_SUCCESS);
 186     }
 187
 188     /* Retrieve group list. */
 189
 190     if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) {
 191         fprintf(stderr, "getgrouplist() returned \-1; ngroups = %d\en",
 192                 ngroups);
 193         exit(EXIT_FAILURE);
 194     }
 195
 196     /* Display list of retrieved groups, along with group names. */
 197
 198     fprintf(stderr, "ngroups = %d\en", ngroups);
 199     for (int j = 0; j < ngroups; j++) {
 200         printf("%d", groups[j]);
 201         gr = getgrgid(groups[j]);
 202         if (gr != NULL)
 203             printf(" (%s)", gr\->gr_name);
 204         printf("\en");
 205     }
 206
 207     exit(EXIT_SUCCESS);
 208 }
 209 .EE
 210 .SH SEE ALSO
 211 .BR getgroups (2),
 212 .BR setgroups (2),
 213 .BR getgrent (3),
 214 .BR group_member (3),
 215 .BR group (5),
 216 .BR passwd (5)