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

NAME

6       getgrent, getgrgid, getgrnam, setgrent, endgrent - get group file entry
7

SYNOPSIS

9       #include <grp.h>
10
11       struct group *getgrent();
12
13       struct group *getgrgid(gid) int gid;
14
15       struct group *getgrnam(name) char *name;
16
17       int setgrent();
18
19       int endgrent();
20

DESCRIPTION

22       Getgrent,  getgrgid and getgrnam each return pointers to an object with
23       the following structure containing the broken-out fields of a  line  in
24       the group file.
25
26              /* Copyright (C) 1991,1992,1995-2001,2003,2004,2010,2012
27                 Free Software Foundation, Inc.
28                 This file is part of the GNU C Library.
29
30                 The GNU C Library is free software; you can redistribute it and/or
31                 modify it under the terms of the GNU Lesser General Public
32                 License as published by the Free Software Foundation; either
33                 version 2.1 of the License, or (at your option) any later version.
34
35                 The GNU C Library is distributed in the hope that it will be useful,
36                 but WITHOUT ANY WARRANTY; without even the implied warranty of
37                 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
38                 Lesser General Public License for more details.
39
40                 You should have received a copy of the GNU Lesser General Public
41                 License along with the GNU C Library; if not, see
42                 <http://www.gnu.org/licenses/>.  */
43
44              /*
45               *   POSIX Standard: 9.2.1 Group Database Access  <grp.h>
46               */
47
48              #ifndef   _GRP_H
49              #define   _GRP_H    1
50
51              #include <features.h>
52
53              __BEGIN_DECLS
54
55              #include <bits/types.h>
56
57              #define __need_size_t
58              #include <stddef.h>
59
60
61              /* For the Single Unix specification we must define this type here.  */
62              #if (defined __USE_XOPEN || defined __USE_XOPEN2K) && !defined __gid_t_defined
63              typedef __gid_t gid_t;
64              # define __gid_t_defined
65              #endif
66
67              /* The group structure.   */
68              struct group
69                {
70                  char *gr_name;       /* Group name. */
71                  char *gr_passwd;          /* Password.   */
72                  __gid_t gr_gid;      /* Group ID.   */
73                  char **gr_mem;       /* Member list.     */
74                };
75
76
77              #if defined __USE_SVID || defined __USE_GNU
78              # define __need_FILE
79              # include <stdio.h>
80              #endif
81
82
83              #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN_EXTENDED
84              /* Rewind the group-file stream.
85
86                 This function is a possible cancellation point and therefore not
87                 marked with __THROW.  */
88              extern void setgrent (void);
89              #endif
90
91              #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN_EXTENDED     || defined __USE_XOPEN2K8
92              /* Close the group-file stream.
93
94                 This function is a possible cancellation point and therefore not
95                 marked with __THROW.  */
96              extern void endgrent (void);
97
98              /* Read an entry from the group-file stream, opening it if necessary.
99
100                 This function is a possible cancellation point and therefore not
101                 marked with __THROW.  */
102              extern struct group *getgrent (void);
103              #endif
104
105              #ifdef    __USE_SVID
106              /* Read a group entry from STREAM.
107
108                 This function is not part of POSIX and therefore no official
109                 cancellation point.  But due to similarity with an POSIX interface
110                 or due to the implementation it is a cancellation point and
111                 therefore not marked with __THROW.  */
112              extern struct group *fgetgrent (FILE *__stream);
113              #endif
114
115              #ifdef __USE_GNU
116              /* Write the given entry onto the given stream.
117
118                 This function is not part of POSIX and therefore no official
119                 cancellation point.  But due to similarity with an POSIX interface
120                 or due to the implementation it is a cancellation point and
121                 therefore not marked with __THROW.  */
122              extern int putgrent (const struct group *__restrict __p,
123                             FILE *__restrict __f);
124              #endif
125
126              /* Search for an entry with a matching group ID.
127
128                 This function is a possible cancellation point and therefore not
129                 marked with __THROW.  */
130              extern struct group *getgrgid (__gid_t __gid);
131
132              /* Search for an entry with a matching group name.
133
134                 This function is a possible cancellation point and therefore not
135                 marked with __THROW.  */
136              extern struct group *getgrnam (const char *__name);
137
138              #if defined __USE_POSIX || defined __USE_MISC
139
140              # ifdef __USE_MISC
141              /* Reasonable value for the buffer sized used in the reentrant
142                 functions below.  But better use `sysconf'.  */
143              #  define NSS_BUFLEN_GROUP    1024
144              # endif
145
146              /* Reentrant versions of some of the functions above.
147
148                 PLEASE NOTE: the `getgrent_r' function is not (yet) standardized.
149                 The interface may change in later versions of this library.  But
150                 the interface is designed following the principals used for the
151                 other reentrant functions so the chances are good this is what the
152                 POSIX people would choose.
153
154                 This function is not part of POSIX and therefore no official
155                 cancellation point.  But due to similarity with an POSIX interface
156                 or due to the implementation it is a cancellation point and
157                 therefore not marked with __THROW.  */
158
159              # ifdef __USE_GNU
160              extern int getgrent_r (struct group *__restrict __resultbuf,
161                               char *__restrict __buffer, size_t __buflen,
162                               struct group **__restrict __result);
163              # endif
164
165              /* Search for an entry with a matching group ID.
166
167                 This function is a possible cancellation point and therefore not
168                 marked with __THROW.  */
169              extern int getgrgid_r (__gid_t __gid, struct group *__restrict __resultbuf,
170                               char *__restrict __buffer, size_t __buflen,
171                               struct group **__restrict __result);
172
173              /* Search for an entry with a matching group name.
174
175                 This function is a possible cancellation point and therefore not
176                 marked with __THROW.  */
177              extern int getgrnam_r (const char *__restrict __name,
178                               struct group *__restrict __resultbuf,
179                               char *__restrict __buffer, size_t __buflen,
180                               struct group **__restrict __result);
181
182              # ifdef   __USE_SVID
183              /* Read a group entry from STREAM.  This function is not standardized
184                 an probably never will.
185
186                 This function is not part of POSIX and therefore no official
187                 cancellation point.  But due to similarity with an POSIX interface
188                 or due to the implementation it is a cancellation point and
189                 therefore not marked with __THROW.  */
190              extern int fgetgrent_r (FILE *__restrict __stream,
191                             struct group *__restrict __resultbuf,
192                             char *__restrict __buffer, size_t __buflen,
193                             struct group **__restrict __result);
194              # endif
195
196              #endif    /* POSIX or reentrant */
197
198
199              #ifdef    __USE_BSD
200
201              # define __need_size_t
202              # include <stddef.h>
203
204              /* Set the group set for the current user to GROUPS (N of them).  */
205              extern int setgroups (size_t __n, const __gid_t *__groups) __THROW;
206
207              /* Store at most *NGROUPS members of the group set for USER into
208                 *GROUPS.  Also include GROUP.  The actual number of groups found is
209                 returned in *NGROUPS.  Return -1 if the if *NGROUPS is too small.
210
211                 This function is not part of POSIX and therefore no official
212                 cancellation point.  But due to similarity with an POSIX interface
213                 or due to the implementation it is a cancellation point and
214                 therefore not marked with __THROW.  */
215              extern int getgrouplist (const char *__user, __gid_t __group,
216                              __gid_t *__groups, int *__ngroups);
217
218              /* Initialize the group set for the current user
219                 by reading the group database and using all groups
220                 of which USER is a member.  Also include GROUP.
221
222                 This function is not part of POSIX and therefore no official
223                 cancellation point.  But due to similarity with an POSIX interface
224                 or due to the implementation it is a cancellation point and
225                 therefore not marked with __THROW.  */
226              extern int initgroups (const char *__user, __gid_t __group);
227
228              #endif /* Use BSD.  */
229
230              __END_DECLS
231
232              #endif /* grp.h  */
233
234       The members of this structure are:
235
236       gr_name
237              The name of the group.
238       gr_passwd
239              The encrypted password of the group.
240       gr_gid The numerical group-ID.
241       gr_mem Null-terminated  vector  of  pointers  to  the individual member
242              names.
243
244       Getgrent simply reads the next line while getgrgid and getgrnam  search
245       until  a  matching  gid or name is found (or until EOF is encountered).
246       Each routine picks up where the others leave off  so  successive  calls
247       may be used to search the entire file.
248
249       A  call to setgrent has the effect of rewinding the group file to allow
250       repeated searches.  Endgrent may be called to close the group file when
251       processing is complete.
252

FILES

254       /etc/group
255

SEE ALSO

257       getlogin(3), getpwent(3), group(5)
258

DIAGNOSTICS

260       A null pointer (0) is returned on EOF or error.
261

BUGS

263       All  information  is contained in a static area so it must be copied if
264       it is to be saved.
265
266
267
268                                                                   GETGRENT(3)
Impressum