1GETGRENT(3) Library Functions Manual GETGRENT(3)
2
6 getgrent, getgrgid, getgrnam, setgrent, endgrent - get group file entry
7
9 #include <grp.h>
10 struct group *getgrent()
12 struct group *getgrgid(gid)
14 int gid;
15 struct group *getgrnam(name)
17 char *name;
18 setgrent()
20 endgrent()
22
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 /* 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 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 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 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 /*
47 * POSIX Standard: 9.2.1 Group Database Access <grp.h>
48 */
49 #ifndef _GRP_H
51 #define _GRP_H 1
52 #include <features.h>
54 __BEGIN_DECLS
56 #include <bits/types.h>
58 #define __need_size_t
60 #include <stddef.h>
61 /* 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 /* 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 #if defined __USE_SVID || defined __USE_GNU
80 # define __need_FILE
81 # include <stdio.h>
82 #endif
83 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN_EXTENDED
86 /* Rewind the group-file stream.
87 This function is a possible cancellation point and therefore not
89 marked with __THROW. */
90 extern void setgrent (void);
91 #endif
92 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN_EXTENDED || defined __USE_XOPEN2K8
94 /* Close the group-file stream.
95 This function is a possible cancellation point and therefore not
97 marked with __THROW. */
98 extern void endgrent (void);
99 /* Read an entry from the group-file stream, opening it if necessary.
101 This function is a possible cancellation point and therefore not
103 marked with __THROW. */
104 extern struct group *getgrent (void);
105 #endif
106 #ifdef __USE_SVID
108 /* Read a group entry from STREAM.
109 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 #ifdef __USE_GNU
118 /* Write the given entry onto the given stream.
119 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 /* Search for an entry with a matching group ID.
129 This function is a possible cancellation point and therefore not
131 marked with __THROW. */
132 extern struct group *getgrgid (__gid_t __gid);
133 /* Search for an entry with a matching group name.
135 This function is a possible cancellation point and therefore not
137 marked with __THROW. */
138 extern struct group *getgrnam (const char *__name);
139 #if defined __USE_POSIX || defined __USE_MISC
141 # 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 /* Reentrant versions of some of the functions above.
149 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 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 # 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 /* Search for an entry with a matching group ID.
168 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 /* Search for an entry with a matching group name.
176 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 # ifdef __USE_SVID
185 /* Read a group entry from STREAM. This function is not standardized
186 an probably never will.
187 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 #endif /* POSIX or reentrant */
199 #ifdef __USE_BSD
202 # define __need_size_t
204 # include <stddef.h>
205 /* 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 /* 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 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 /* 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 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 #endif /* Use BSD. */
231 __END_DECLS
233 #endif /* grp.h */
235 The members of this structure are:
237 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 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 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
254 /etc/group
255
257 getlogin(3), getpwent(3), group(5)
258
260 A null pointer (0) is returned on EOF or error.
261
263 All information is contained in a static area so it must be copied if
264 it is to be saved.
2657th Edition May 15, 1985 GETGRENT(3)