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 2021-03-22 "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 *restrict " gbuf ,
  32 .BI "               char *restrict " buf ", size_t " buflen ,
  33 .BI "               struct group **restrict " gbufp );
  34 .BI "int fgetgrent_r(FILE *restrict " stream ", struct group *restrict " gbuf ,
  35 .BI "               char *restrict " buf ", size_t " buflen ,
  36 .BI "               struct group **restrict " gbufp );
  37 .fi
  38 .PP
  39 .RS -4
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .RE
  43 .PP
  44 .BR getgrent_r ():
  45 .nf
  46     _GNU_SOURCE
  47 .fi
  48 .\" FIXME . The FTM requirements seem inconsistent here.  File a glibc bug?
  49 .PP
  50 .BR fgetgrent_r ():
  51     Since glibc 2.19:
  52         _DEFAULT_SOURCE
  53     Glibc 2.19 and earlier:
  54         _SVID_SOURCE
  55 .SH DESCRIPTION
  56 The functions
  57 .BR getgrent_r ()
  58 and
  59 .BR fgetgrent_r ()
  60 are the reentrant versions of
  61 .BR getgrent (3)
  62 and
  63 .BR fgetgrent (3).
  64 The former reads the next group entry from the stream initialized by
  65 .BR setgrent (3).
  66 The latter reads the next group entry from
  67 .IR stream .
  68 .PP
  69 The \fIgroup\fP structure is defined in
  70 .I <grp.h>
  71 as follows:
  72 .PP
  73 .in +4n
  74 .EX
  75 struct group {
  76     char   *gr_name;        /* group name */
  77     char   *gr_passwd;      /* group password */
  78     gid_t   gr_gid;         /* group ID */
  79     char  **gr_mem;         /* NULL\-terminated array of pointers
  80                                to names of group members */
  81 };
  82 .EE
  83 .in
  84 .PP
  85 For more information about the fields of this structure, see
  86 .BR group (5).
  87 .PP
  88 The nonreentrant functions return a pointer to static storage,
  89 where this static storage contains further pointers to group
  90 name, password, and members.
  91 The reentrant functions described here return all of that in
  92 caller-provided buffers.
  93 First of all there is the buffer
  94 .I gbuf
  95 that can hold a \fIstruct group\fP.
  96 And next the buffer
  97 .I buf
  98 of size
  99 .I buflen
 100 that can hold additional strings.
 101 The result of these functions, the \fIstruct group\fP read from the stream,
 102 is stored in the provided buffer
 103 .IR *gbuf ,
 104 and a pointer to this \fIstruct group\fP is returned in
 105 .IR *gbufp .
 106 .SH RETURN VALUE
 107 On success, these functions return 0 and
 108 .I *gbufp
 109 is a pointer to the \fIstruct group\fP.
 110 On error, these functions return an error value and
 111 .I *gbufp
 112 is NULL.
 113 .SH ERRORS
 114 .TP
 115 .B ENOENT
 116 No more entries.
 117 .TP
 118 .B ERANGE
 119 Insufficient buffer space supplied.
 120 Try again with larger buffer.
 121 .SH ATTRIBUTES
 122 For an explanation of the terms used in this section, see
 123 .BR attributes (7).
 124 .ad l
 125 .nh
 126 .TS
 127 allbox;
 128 lb lb lbx
 129 l l l.
 130 Interface       Attribute       Value
 131 T{
 132 .BR getgrent_r ()
 133 T}      Thread safety   T{
 134 MT-Unsafe race:grent locale
 135 T}
 136 T{
 137 .BR fgetgrent_r ()
 138 T}      Thread safety   T{
 139 MT-Safe
 140 T}
 141 .TE
 142 .hy
 143 .ad
 144 .sp 1
 145 In the above table,
 146 .I grent
 147 in
 148 .I race:grent
 149 signifies that if any of the functions
 150 .BR setgrent (3),
 151 .BR getgrent (3),
 152 .BR endgrent (3),
 153 or
 154 .BR getgrent_r ()
 155 are used in parallel in different threads of a program,
 156 then data races could occur.
 157 .SH CONFORMING TO
 158 These functions are GNU extensions, done in a style resembling
 159 the POSIX version of functions like
 160 .BR getpwnam_r (3).
 161 Other systems use the prototype
 162 .PP
 163 .in +4n
 164 .EX
 165 struct group *getgrent_r(struct group *grp, char *buf,
 166                          int buflen);
 167 .EE
 168 .in
 169 .PP
 170 or, better,
 171 .PP
 172 .in +4n
 173 .EX
 174 int getgrent_r(struct group *grp, char *buf, int buflen,
 175                FILE **gr_fp);
 176 .EE
 177 .in
 178 .SH NOTES
 179 The function
 180 .BR getgrent_r ()
 181 is not really reentrant since it shares the reading position
 182 in the stream with all other threads.
 183 .SH EXAMPLES
 184 .EX
 185 #define _GNU_SOURCE
 186 #include <grp.h>
 187 #include <stdio.h>
 188 #include <stdint.h>
 189 #include <stdlib.h>
 190 #define BUFLEN 4096
 191
 192 int
 193 main(void)
 194 {
 195     struct group grp;
 196     struct group *grpp;
 197     char buf[BUFLEN];
 198     int i;
 199
 200     setgrent();
 201     while (1) {
 202         i = getgrent_r(&grp, buf, sizeof(buf), &grpp);
 203         if (i)
 204             break;
 205         printf("%s (%jd):", grpp\->gr_name, (intmax_t) grpp\->gr_gid);
 206         for (int j = 0; ; j++) {
 207             if (grpp\->gr_mem[j] == NULL)
 208                 break;
 209             printf(" %s", grpp\->gr_mem[j]);
 210         }
 211         printf("\en");
 212     }
 213     endgrent();
 214     exit(EXIT_SUCCESS);
 215 }
 216 .EE
 217 .\" perhaps add error checking - should use strerror_r
 218 .\" #include <errno.h>
 219 .\" #include <stdlib.h>
 220 .\"         if (i) {
 221 .\"               if (i == ENOENT)
 222 .\"                     break;
 223 .\"               printf("getgrent_r: %s", strerror(i));
 224 .\"               exit(EXIT_FAILURE);
 225 .\"         }
 226 .SH SEE ALSO
 227 .BR fgetgrent (3),
 228 .BR getgrent (3),
 229 .BR getgrgid (3),
 230 .BR getgrnam (3),
 231 .BR putgrent (3),
 232 .BR group (5)