man3/getgrent_r.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .TH GETGRENT_R 3 2017-09-15 "GNU" "Linux Programmer's Manual"
  25 .SH NAME
  26 getgrent_r, fgetgrent_r \- get group file entry reentrantly
  27 .SH SYNOPSIS
  28 .nf
  29 .B #include <grp.h>
  30 .PP
  31 .BI "int getgrent_r(struct group *" gbuf ", char *" buf ,
  32 .BI "               size_t " buflen ", struct group **" gbufp );
  33 .PP
  34 .BI "int fgetgrent_r(FILE *" stream ", struct group *" gbuf ", char *" buf ,
  35 .BI "                size_t " buflen ", struct group **" gbufp );
  36 .fi
  37 .PP
  38 .in -4n
  39 Feature Test Macro Requirements for glibc (see
  40 .BR feature_test_macros (7)):
  41 .in
  42 .PP
  43 .BR getgrent_r ():
  44 _GNU_SOURCE
  45 .\" FIXME . The FTM requirements seem inconsistent here.  File a glibc bug?
  46 .br
  47 .BR fgetgrent_r ():
  48     Since glibc 2.19:
  49         _DEFAULT_SOURCE
  50     Glibc 2.19 and earlier:
  51         _SVID_SOURCE
  52 .SH DESCRIPTION
  53 The functions
  54 .BR getgrent_r ()
  55 and
  56 .BR fgetgrent_r ()
  57 are the reentrant versions of
  58 .BR getgrent (3)
  59 and
  60 .BR fgetgrent (3).
  61 The former reads the next group entry from the stream initialized by
  62 .BR setgrent (3).
  63 The latter reads the next group entry from
  64 .IR stream .
  65 .PP
  66 The \fIgroup\fP structure is defined in
  67 .I <grp.h>
  68 as follows:
  69 .PP
  70 .in +4n
  71 .EX
  72 struct group {
  73     char   *gr_name;        /* group name */
  74     char   *gr_passwd;      /* group password */
  75     gid_t   gr_gid;         /* group ID */
  76     char  **gr_mem;         /* NULL-terminated array of pointers
  77                                to names of group members */
  78 };
  79 .EE
  80 .in
  81 .PP
  82 For more information about the fields of this structure, see
  83 .BR group (5).
  84 .PP
  85 The nonreentrant functions return a pointer to static storage,
  86 where this static storage contains further pointers to group
  87 name, password and members.
  88 The reentrant functions described here return all of that in
  89 caller-provided buffers.
  90 First of all there is the buffer
  91 .I gbuf
  92 that can hold a \fIstruct group\fP.
  93 And next the buffer
  94 .I buf
  95 of size
  96 .I buflen
  97 that can hold additional strings.
  98 The result of these functions, the \fIstruct group\fP read from the stream,
  99 is stored in the provided buffer
 100 .IR *gbuf ,
 101 and a pointer to this \fIstruct group\fP is returned in
 102 .IR *gbufp .
 103 .SH RETURN VALUE
 104 On success, these functions return 0 and
 105 .I *gbufp
 106 is a pointer to the \fIstruct group\fP.
 107 On error, these functions return an error value and
 108 .I *gbufp
 109 is NULL.
 110 .SH ERRORS
 111 .TP
 112 .B ENOENT
 113 No more entries.
 114 .TP
 115 .B ERANGE
 116 Insufficient buffer space supplied.
 117 Try again with larger buffer.
 118 .SH ATTRIBUTES
 119 For an explanation of the terms used in this section, see
 120 .BR attributes (7).
 121 .TS
 122 allbox;
 123 lb lb lbw27
 124 l l l.
 125 Interface       Attribute       Value
 126 T{
 127 .BR getgrent_r ()
 128 T}      Thread safety   MT-Unsafe race:grent locale
 129 T{
 130 .BR fgetgrent_r ()
 131 T}      Thread safety   MT-Safe
 132 .TE
 133 .sp 1
 134 In the above table,
 135 .I grent
 136 in
 137 .I race:grent
 138 signifies that if any of the functions
 139 .BR setgrent (),
 140 .BR getgrent (),
 141 .BR endgrent (),
 142 or
 143 .BR getgrent_r ()
 144 are used in parallel in different threads of a program,
 145 then data races could occur.
 146 .SH CONFORMING TO
 147 These functions are GNU extensions, done in a style resembling
 148 the POSIX version of functions like
 149 .BR getpwnam_r (3).
 150 Other systems use the prototype
 151 .PP
 152 .in +4n
 153 .EX
 154 struct group *getgrent_r(struct group *grp, char *buf,
 155                          int buflen);
 156 .EE
 157 .in
 158 .PP
 159 or, better,
 160 .PP
 161 .in +4n
 162 .EX
 163 int getgrent_r(struct group *grp, char *buf, int buflen,
 164                FILE **gr_fp);
 165 .EE
 166 .in
 167 .SH NOTES
 168 The function
 169 .BR getgrent_r ()
 170 is not really reentrant since it shares the reading position
 171 in the stream with all other threads.
 172 .SH EXAMPLE
 173 .EX
 174 #define _GNU_SOURCE
 175 #include <grp.h>
 176 #include <stdio.h>
 177 #include <stdlib.h>
 178 #define BUFLEN 4096
 179
 180 int
 181 main(void)
 182 {
 183     struct group grp, *grpp;
 184     char buf[BUFLEN];
 185     int i;
 186
 187     setgrent();
 188     while (1) {
 189         i = getgrent_r(&grp, buf, BUFLEN, &grpp);
 190         if (i)
 191             break;
 192         printf("%s (%d):", grpp\->gr_name, grpp\->gr_gid);
 193         for (i = 0; ; i++) {
 194             if (grpp\->gr_mem[i] == NULL)
 195                 break;
 196             printf(" %s", grpp\->gr_mem[i]);
 197         }
 198         printf("\en");
 199     }
 200     endgrent();
 201     exit(EXIT_SUCCESS);
 202 }
 203 .EE
 204 .\" perhaps add error checking - should use strerror_r
 205 .\" #include <errno.h>
 206 .\" #include <stdlib.h>
 207 .\"         if (i) {
 208 .\"               if (i == ENOENT)
 209 .\"                     break;
 210 .\"               printf("getgrent_r: %s", strerror(i));
 211 .\"               exit(EXIT_FAILURE);
 212 .\"         }
 213 .SH SEE ALSO
 214 .BR fgetgrent (3),
 215 .BR getgrent (3),
 216 .BR getgrgid (3),
 217 .BR getgrnam (3),
 218 .BR putgrent (3),
 219 .BR group (5)