getgrent_r(3)

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

NAME

6       getgrent_r, fgetgrent_r - get group file entry reentrantly
7

SYNOPSIS

9       #define _GNU_SOURCE
10       #include <grp.h>
11
12       int getgrent_r(struct group *gbuf, char *buf,
13                      size_t buflen, struct group **gbufp);
14
15       int fgetgrent_r(FILE *fp, struct group *gbuf, char *buf,
16                       size_t buflen, struct group **gbufp);
17

DESCRIPTION

19       The functions getgrent_r() and fgetgrent_r() are the reentrant versions
20       of getgrent(3) and fgetgrent(3).  The former reads the next group entry
21       from  the stream initialized by setgrent(3).  The latter reads the next
22       group entry from the stream fp given as parameter.
23
24       The group structure is defined in <grp.h> as follows:
25
26              struct group {
27                    char    *gr_name;      /* group name */
28                    char    *gr_passwd;    /* group password */
29                    gid_t   gr_gid;        /* group ID */
30                    char    **gr_mem;      /* group members */
31              };
32
33       The non-reentrant functions return a pointer to static  storage,  where
34       this  static  storage contains further pointers to group name, password
35       and members.  The reentrant functions described here return all of that
36       in  caller-provided buffers. First of all there is the buffer gbuf that
37       can hold a struct group. And next the buffer buf of  size  buflen  that
38       can hold additional strings.  The result of these functions, the struct
39       group read from the stream, is stored in the provided buffer *gbuf, and
40       a pointer to this struct group is returned in *gbufp.
41

RETURN VALUE

43       On  success,  these  functions  return 0 and *gbufp is a pointer to the
44       struct group.  On error, these functions  return  an  error  value  and
45       *gbufp is NULL.
46

ERRORS

48       ENOENT No more entries.
49
50       ERANGE Insufficient  buffer  space supplied. Try again with larger buf‐
51              fer.
52

EXAMPLE

54       #define _GNU_SOURCE
55       #include <grp.h>
56       #include <stdio.h>
57       #define BUFLEN 4096
58
59       int main() {
60             struct group grp, *grpp;
61             char buf[BUFLEN];
62             int i;
63
64             setgrent();
65             while (1) {
66                   i = getgrent_r(&grp, buf, BUFLEN, &grpp);
67                   if (i)
68                         break;
69                   printf("%s (%d):", grpp->gr_name, grpp->gr_gid);
70                   for (i = 0; ; i++) {
71                         if (grpp->gr_mem[i] == NULL)
72                               break;
73                         printf(" %s", grpp->gr_mem[i]);
74                   }
75                   printf("\n");
76             }
77             endgrent();
78             return 0;
79       }
80

CONFORMING TO

82       These functions are GNU extensions, done  in  a  style  resembling  the
83       POSIX  version of functions like getpwnam_r(3).  Other systems use pro‐
84       totype
85
86           struct group *
87           getgrent_r(struct group *grp, char *buf, int buflen);
88
89       or, better,
90
91           int
92           getgrent_r(struct group *grp, char *buf, int buflen,
93                      FILE **gr_fp);
94
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