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 (date) "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 .\" SRC BEGIN (getgrouplist.c)
 138 .EX
 139 #include <grp.h>
 140 #include <pwd.h>
 141 #include <stdio.h>
 142 #include <stdlib.h>
 143
 144 int
 145 main(int argc, char *argv[])
 146 {
 147     int ngroups;
 148     struct passwd *pw;
 149     struct group *gr;
 150     gid_t *groups;
 151
 152     if (argc != 3) {
 153         fprintf(stderr, "Usage: %s <user> <ngroups>\en", argv[0]);
 154         exit(EXIT_FAILURE);
 155     }
 156
 157     ngroups = atoi(argv[2]);
 158
 159     groups = malloc(sizeof(*groups) * ngroups);
 160     if (groups == NULL) {
 161         perror("malloc");
 162         exit(EXIT_FAILURE);
 163     }
 164
 165     /* Fetch passwd structure (contains first group ID for user). */
 166
 167     pw = getpwnam(argv[1]);
 168     if (pw == NULL) {
 169         perror("getpwnam");
 170         exit(EXIT_SUCCESS);
 171     }
 172
 173     /* Retrieve group list. */
 174
 175     if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) {
 176         fprintf(stderr, "getgrouplist() returned \-1; ngroups = %d\en",
 177                 ngroups);
 178         exit(EXIT_FAILURE);
 179     }
 180
 181     /* Display list of retrieved groups, along with group names. */
 182
 183     fprintf(stderr, "ngroups = %d\en", ngroups);
 184     for (size_t j = 0; j < ngroups; j++) {
 185         printf("%d", groups[j]);
 186         gr = getgrgid(groups[j]);
 187         if (gr != NULL)
 188             printf(" (%s)", gr\->gr_name);
 189         printf("\en");
 190     }
 191
 192     exit(EXIT_SUCCESS);
 193 }
 194 .EE
 195 .\" SRC END
 196 .SH SEE ALSO
 197 .BR getgroups (2),
 198 .BR setgroups (2),
 199 .BR getgrent (3),
 200 .BR group_member (3),
 201 .BR group (5),
 202 .BR passwd (5)