getgrent_r(3)

1getgrent_r(3)              Library Functions Manual              getgrent_r(3)
2
3
4

NAME

6       getgrent_r, fgetgrent_r - get group file entry reentrantly
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

60       On  success,  these  functions  return 0 and *gbufp is a pointer to the
61       struct group.  On error, these functions  return  an  error  value  and
62       *gbufp is NULL.
63

ERRORS

65       ENOENT No more entries.
66
67       ERANGE Insufficient  buffer space supplied.  Try again with larger buf‐
68              fer.
69

ATTRIBUTES

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

VERSIONS

87       Other systems use the prototype
88
89           struct group *getgrent_r(struct group *grp, char *buf,
90                                    int buflen);
91
92       or, better,
93
94           int getgrent_r(struct group *grp, char *buf, int buflen,
95                          FILE **gr_fp);
96

STANDARDS

98       GNU.
99

HISTORY

101       These functions are done in a style resembling  the  POSIX  version  of
102       functions like getpwnam_r(3).
103

NOTES

105       The  function  getgrent_r() is not really reentrant since it shares the
106       reading position in the stream with all other threads.
107

EXAMPLES

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