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)
14       int gid;
15
16       struct group *getgrnam(name)
17       char *name;
18
19       setgrent()
20
21       endgrent()
22

DESCRIPTION

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