man3/getgrouplist.3

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