getgrent_r(3)

1GETGRENT_R(3)              Linux Programmer's Manual             GETGRENT_R(3)
2
3
4

NAME

6       getgrent_r, fgetgrent_r - get group file entry reentrantly
7

SYNOPSIS

9       #include <grp.h>
10
11       int getgrent_r(struct group *restrict gbuf,
12                      char *restrict buf, size_t buflen,
13                      struct group **restrict gbufp);
14       int fgetgrent_r(FILE *restrict stream, struct group *restrict gbuf,
15                      char *restrict buf, size_t buflen,
16                      struct group **restrict gbufp);
17
18   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19
20       getgrent_r():
21           _GNU_SOURCE
22
23       fgetgrent_r():
24           Since glibc 2.19:
25               _DEFAULT_SOURCE
26           Glibc 2.19 and earlier:
27               _SVID_SOURCE
28

DESCRIPTION

30       The functions getgrent_r() and fgetgrent_r() are the reentrant versions
31       of getgrent(3) and fgetgrent(3).  The former reads the next group entry
32       from  the stream initialized by setgrent(3).  The latter reads the next
33       group entry from stream.
34
35       The group structure is defined in <grp.h> as follows:
36
37           struct group {
38               char   *gr_name;        /* group name */
39               char   *gr_passwd;      /* group password */
40               gid_t   gr_gid;         /* group ID */
41               char  **gr_mem;         /* NULL-terminated array of pointers
42                                          to names of group members */
43           };
44
45       For more information about the fields of this structure, see group(5).
46
47       The nonreentrant functions return a pointer to  static  storage,  where
48       this  static storage contains further pointers to group name, password,
49       and members.  The reentrant functions described here return all of that
50       in caller-provided buffers.  First of all there is the buffer gbuf that
51       can hold a struct group.  And next the buffer buf of size  buflen  that
52       can hold additional strings.  The result of these functions, the struct
53       group read from the stream, is stored in the provided buffer *gbuf, and
54       a pointer to this struct group is returned in *gbufp.
55

RETURN VALUE

57       On  success,  these  functions  return 0 and *gbufp is a pointer to the
58       struct group.  On error, these functions  return  an  error  value  and
59       *gbufp is NULL.
60

ERRORS

62       ENOENT No more entries.
63
64       ERANGE Insufficient  buffer space supplied.  Try again with larger buf‐
65              fer.
66

ATTRIBUTES

68       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
69       tributes(7).
70
71       ┌──────────────┬───────────────┬───────────────────────────────────────┐
72       │Interface     │ Attribute     │ Value                                 │
73       ├──────────────┼───────────────┼───────────────────────────────────────┤
74       │getgrent_r()  │ Thread safety │ MT-Unsafe race:grent locale           │
75       ├──────────────┼───────────────┼───────────────────────────────────────┤
76       │fgetgrent_r() │ Thread safety │ MT-Safe                               │
77       └──────────────┴───────────────┴───────────────────────────────────────┘
78       In  the  above  table, grent in race:grent signifies that if any of the
79       functions setgrent(3), getgrent(3), endgrent(3),  or  getgrent_r()  are
80       used  in  parallel  in  different threads of a program, then data races
81       could occur.
82

CONFORMING TO

84       These functions are GNU extensions, done  in  a  style  resembling  the
85       POSIX  version  of functions like getpwnam_r(3).  Other systems use the
86       prototype
87
88           struct group *getgrent_r(struct group *grp, char *buf,
89                                    int buflen);
90
91       or, better,
92
93           int getgrent_r(struct group *grp, char *buf, int buflen,
94                          FILE **gr_fp);
95

NOTES

97       The function getgrent_r() is not really reentrant since it  shares  the
98       reading position in the stream with all other threads.
99

EXAMPLES

101       #define _GNU_SOURCE
102       #include <grp.h>
103       #include <stdio.h>
104       #include <stdint.h>
105       #include <stdlib.h>
106       #define BUFLEN 4096
107
108       int
109       main(void)
110       {
111           struct group grp;
112           struct group *grpp;
113           char buf[BUFLEN];
114           int i;
115
116           setgrent();
117           while (1) {
118               i = getgrent_r(&grp, buf, sizeof(buf), &grpp);
119               if (i)
120                   break;
121               printf("%s (%jd):", grpp->gr_name, (intmax_t) grpp->gr_gid);
122               for (int j = 0; ; j++) {
123                   if (grpp->gr_mem[j] == NULL)
124                       break;
125                   printf(" %s", grpp->gr_mem[j]);
126               }
127               printf("\n");
128           }
129           endgrent();
130           exit(EXIT_SUCCESS);
131       }
132

COLOPHON

138       This page is part of release 5.12 of the Linux  man-pages  project.   A
139       description  of  the project, information about reporting bugs, and the
140       latest    version    of    this    page,    can     be     found     at
141       https://www.kernel.org/doc/man-pages/.
142
143
144
145GNU                               2021-03-22                     GETGRENT_R(3)