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 *gbuf, char *buf,
12                      size_t buflen, struct group **gbufp);
13
14       int fgetgrent_r(FILE *stream, struct group *gbuf, char *buf,
15                       size_t buflen, struct group **gbufp);
16
17   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
18
19       getgrent_r(): _GNU_SOURCE
20       fgetgrent_r():
21           Since glibc 2.19:
22               _DEFAULT_SOURCE
23           Glibc 2.19 and earlier:
24               _SVID_SOURCE
25

DESCRIPTION

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

RETURN VALUE

54       On  success,  these  functions  return 0 and *gbufp is a pointer to the
55       struct group.  On error, these functions  return  an  error  value  and
56       *gbufp is NULL.
57

ERRORS

59       ENOENT No more entries.
60
61       ERANGE Insufficient  buffer space supplied.  Try again with larger buf‐
62              fer.
63

ATTRIBUTES

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

CONFORMING TO

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

NOTES

94       The function getgrent_r() is not really reentrant since it  shares  the
95       reading position in the stream with all other threads.
96

EXAMPLES

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

COLOPHON

135       This page is part of release 5.10 of the Linux  man-pages  project.   A
136       description  of  the project, information about reporting bugs, and the
137       latest    version    of    this    page,    can     be     found     at
138       https://www.kernel.org/doc/man-pages/.
139
140
141
142GNU                               2020-11-01                     GETGRENT_R(3)