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 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   8 .\"
   9 .TH GETGROUPLIST 3 2021-03-22 "Linux man-pages (unreleased)"
  10 .SH NAME
  11 getgrouplist \- get list of groups to which a user belongs
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <grp.h>
  18 .PP
  19 .BI "int getgrouplist(const char *" user ", gid_t " group ,
  20 .BI "                 gid_t *" groups ", int *" ngroups );
  21 .fi
  22 .PP
  23 .RS -4
  24 Feature Test Macro Requirements for glibc (see
  25 .BR feature_test_macros (7)):
  26 .RE
  27 .PP
  28 .BR getgrouplist ():
  29 .nf
  30     Since glibc 2.19:
  31         _DEFAULT_SOURCE
  32     Glibc 2.19 and earlier:
  33         _BSD_SOURCE
  34 .fi
  35 .SH DESCRIPTION
  36 The
  37 .BR getgrouplist ()
  38 function scans the group database (see
  39 .BR group (5))
  40 to obtain the list of groups that
  41 .I user
  42 belongs to.
  43 Up to
  44 .I *ngroups
  45 of these groups are returned in the array
  46 .IR groups .
  47 .PP
  48 If it was not among the groups defined for
  49 .I user
  50 in the group database, then
  51 .I group
  52 is included in the list of groups returned by
  53 .BR getgrouplist ();
  54 typically this argument is specified as the group ID from
  55 the password record for
  56 .IR user .
  57 .PP
  58 The
  59 .I ngroups
  60 argument is a value-result argument:
  61 on return it always contains the number of groups found for
  62 .IR user ,
  63 including
  64 .IR group ;
  65 this value may be greater than the number of groups stored in
  66 .IR groups .
  67 .SH RETURN VALUE
  68 If the number of groups of which
  69 .I user
  70 is a member is less than or equal to
  71 .IR *ngroups ,
  72 then the value
  73 .I *ngroups
  74 is returned.
  75 .PP
  76 If the user is a member of more than
  77 .I *ngroups
  78 groups, then
  79 .BR getgrouplist ()
  80 returns \-1.
  81 In this case, the value returned in
  82 .I *ngroups
  83 can be used to resize the buffer passed to a further call to
  84 .BR getgrouplist ().
  85 .SH VERSIONS
  86 This function is present since glibc 2.2.4.
  87 .SH ATTRIBUTES
  88 For an explanation of the terms used in this section, see
  89 .BR attributes (7).
  90 .ad l
  91 .nh
  92 .TS
  93 allbox;
  94 lbx lb lb
  95 l l l.
  96 Interface       Attribute       Value
  97 T{
  98 .BR getgrouplist ()
  99 T}      Thread safety   MT-Safe locale
 100 .TE
 101 .hy
 102 .ad
 103 .sp 1
 104 .SH STANDARDS
 105 This function is nonstandard; it appears on most BSDs.
 106 .SH BUGS
 107 In glibc versions before 2.3.3,
 108 the implementation of this function contains a buffer-overrun bug:
 109 it returns the complete list of groups for
 110 .I user
 111 in the array
 112 .IR groups ,
 113 even when the number of groups exceeds
 114 .IR *ngroups .
 115 .SH EXAMPLES
 116 The program below displays the group list for the user named in its
 117 first command-line argument.
 118 The second command-line argument specifies the
 119 .I ngroups
 120 value to be supplied to
 121 .BR getgrouplist ().
 122 The following shell session shows examples of the use of this program:
 123 .PP
 124 .in +4n
 125 .EX
 126 .RB "$" " ./a.out cecilia 0"
 127 getgrouplist() returned \-1; ngroups = 3
 128 .RB "$" " ./a.out cecilia 3"
 129 ngroups = 3
 130 16 (dialout)
 131 33 (video)
 132 100 (users)
 133 .EE
 134 .in
 135 .SS Program source
 136 \&
 137 .EX
 138 #include <stdio.h>
 139 #include <stdlib.h>
 140 #include <grp.h>
 141 #include <pwd.h>
 142
 143 int
 144 main(int argc, char *argv[])
 145 {
 146     int ngroups;
 147     struct passwd *pw;
 148     struct group *gr;
 149     gid_t *groups;
 150
 151     if (argc != 3) {
 152         fprintf(stderr, "Usage: %s <user> <ngroups>\en", argv[0]);
 153         exit(EXIT_FAILURE);
 154     }
 155
 156     ngroups = atoi(argv[2]);
 157
 158     groups = malloc(sizeof(*groups) * ngroups);
 159     if (groups == NULL) {
 160         perror("malloc");
 161         exit(EXIT_FAILURE);
 162     }
 163
 164     /* Fetch passwd structure (contains first group ID for user). */
 165
 166     pw = getpwnam(argv[1]);
 167     if (pw == NULL) {
 168         perror("getpwnam");
 169         exit(EXIT_SUCCESS);
 170     }
 171
 172     /* Retrieve group list. */
 173
 174     if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) {
 175         fprintf(stderr, "getgrouplist() returned \-1; ngroups = %d\en",
 176                 ngroups);
 177         exit(EXIT_FAILURE);
 178     }
 179
 180     /* Display list of retrieved groups, along with group names. */
 181
 182     fprintf(stderr, "ngroups = %d\en", ngroups);
 183     for (int j = 0; j < ngroups; j++) {
 184         printf("%d", groups[j]);
 185         gr = getgrgid(groups[j]);
 186         if (gr != NULL)
 187             printf(" (%s)", gr\->gr_name);
 188         printf("\en");
 189     }
 190
 191     exit(EXIT_SUCCESS);
 192 }
 193 .EE
 194 .SH SEE ALSO
 195 .BR getgroups (2),
 196 .BR setgroups (2),
 197 .BR getgrent (3),
 198 .BR group_member (3),
 199 .BR group (5),
 200 .BR passwd (5)