man3/getgrent_r.3

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