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