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