man3/getgrent_r.3

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