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) int gid;
14 struct group *getgrnam(name) char *name;
16 int setgrent();
18 int endgrent();
20
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 /* 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 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 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 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 /*
45 * POSIX Standard: 9.2.1 Group Database Access <grp.h>
46 */
47 #ifndef _GRP_H
49 #define _GRP_H 1
50 #include <features.h>
52 __BEGIN_DECLS
54 #include <bits/types.h>
56 #define __need_size_t
58 #include <stddef.h>
59 /* 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 /* 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 #if defined __USE_SVID || defined __USE_GNU
78 # define __need_FILE
79 # include <stdio.h>
80 #endif
81 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN_EXTENDED
84 /* Rewind the group-file stream.
85 This function is a possible cancellation point and therefore not
87 marked with __THROW. */
88 extern void setgrent (void);
89 #endif
90 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN_EXTENDED || defined __USE_XOPEN2K8
92 /* Close the group-file stream.
93 This function is a possible cancellation point and therefore not
95 marked with __THROW. */
96 extern void endgrent (void);
97 /* Read an entry from the group-file stream, opening it if necessary.
99 This function is a possible cancellation point and therefore not
101 marked with __THROW. */
102 extern struct group *getgrent (void);
103 #endif
104 #ifdef __USE_SVID
106 /* Read a group entry from STREAM.
107 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 #ifdef __USE_GNU
116 /* Write the given entry onto the given stream.
117 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 /* Search for an entry with a matching group ID.
127 This function is a possible cancellation point and therefore not
129 marked with __THROW. */
130 extern struct group *getgrgid (__gid_t __gid);
131 /* Search for an entry with a matching group name.
133 This function is a possible cancellation point and therefore not
135 marked with __THROW. */
136 extern struct group *getgrnam (const char *__name);
137 #if defined __USE_POSIX || defined __USE_MISC
139 # 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 /* Reentrant versions of some of the functions above.
147 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 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 # 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 /* Search for an entry with a matching group ID.
166 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 /* Search for an entry with a matching group name.
174 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 # ifdef __USE_SVID
183 /* Read a group entry from STREAM. This function is not standardized
184 an probably never will.
185 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 #endif /* POSIX or reentrant */
197 #ifdef __USE_BSD
200 # define __need_size_t
202 # include <stddef.h>
203 /* 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 /* 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 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 /* 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 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 #endif /* Use BSD. */
229 __END_DECLS
231 #endif /* grp.h */
233 The members of this structure are:
235 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 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.
265 GETGRENT(3)