1getgrnam(3C) Standard C Library Functions getgrnam(3C)
2
6 getgrnam, getgrnam_r, getgrent, getgrent_r, getgrgid, getgrgid_r, set‐
7 grent, endgrent, fgetgrent, fgetgrent_r - group database entry func‐
8 tions
9
11 #include <grp.h>
12 struct group *getgrnam(const char *name);
14 struct group *getgrnam_r(const char *name, struct group *grp,
17 char *buffer, int bufsize);
18 struct group *getgrent(void);
21 struct group *getgrent_r(struct group *grp, char *buffer, int bufsize);
24 struct group *getgrgid(gid_t gid);
27 struct group *getgrgid_r(gid_t gid, struct group *grp, char *buffer,
30 int bufsize);
31 void setgrent(void);
34 void endgrent(void);
37 struct group *fgetgrent(FILE *f);
40 struct group *fgetgrent_r(FILE *f, struct group *grp, char *buffer,
43 int bufsize);
44 Standard comforming
47 cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]
48 int getgrnam_r(const char *name, struct group *grp, char *buffer,
50 size_t bufsize, struct group **result);
51 int getgrgid_r(gid_t gid, struct group *grp, char *buffer,
54 size_t bufsize, struct group **result);
55
58 These functions are used to obtain entries describing user groups.
59 Entries can come from any of the sources for group specified in the
60 /etc/nsswitch.conf file (see nsswitch.conf(4)).
61 The getgrnam() function searches the group database for an entry with
64 the group name specified by the character string parameter name.
65 The getgrgid() function searches the group database for an entry with
68 the (numeric) group id specified by gid.
69 The setgrent(), getgrent(), and endgrent() functions are used to enu‐
72 merate group entries from the database.
73 The setgrent() function effectively rewinds the group database to allow
76 repeated searches. It sets (or resets) the enumeration to the beginning
77 of the set of group entries. This function should be called before the
78 first call to getgrent().
79 The getgrent() function returns a pointer to a structure containing the
82 broken-out fields of an entry in the group database. When first
83 called, getgrent() returns a pointer to a group structure containing
84 the next group structure in the group database. Successive calls can be
85 used to search the entire database.
86 The endgrent() function can be called to close the group database and
89 deallocate resources when processing is complete. It is permissible,
90 though possibly less efficient, for the process to call more group
91 functions after calling endgrent().
92 The fgetgrent() function, unlike the other functions above, does not
95 use nsswitch.conf. It reads and parses the next line from the stream f,
96 which is assumed to have the format of the group file (see group(4)).
97 Reentrant Interfaces
99 The getgrnam(), getgrgid(), getgrent(), and fgetgrent() functions use
100 thread-specific storage that is reused in each call to one of these
101 functions by the same thread, making them safe to use but not recom‐
102 mended for multithreaded applications.
103 The parallel functions getgrnam_r(), getgrgid_r(), getgrent_r(), and
106 fgetgrent_r() provide reentrant interfaces for these operations.
107 Each reentrant interface performs the same operation as its non-reen‐
110 trant counterpart, named by removing the _r suffix. The reentrant
111 interfaces, however, use buffers supplied by the caller to store
112 returned results instead of using thread-specific data that can be
113 overwritten by each call. They are safe for use in both single-threaded
114 and multithreaded applications.
115 Each reentrant interface takes the same arguments as its non-reentrant
118 counterpart, as well as the following additional parameters. The grp
119 argument must be a pointer to a struct group structure allocated by the
120 caller. On successful completion, the function returns the group entry
121 in this structure. Storage referenced by the group structure is allo‐
122 cated from the memory provided with the buffer argument that is bufsize
123 characters in size. The maximum size needed for this buffer can be
124 determined with the _SC_GETGR_R_SIZE_MAX sysconf(3C) parameter. The
125 standard-conforming versions place a pointer to the modified grp struc‐
126 ture in the result parameter, instead of returning a pointer to this
127 structure. A null pointer is returned at the location pointed to by
128 result on error or if the requested entry is not found.
129 For enumeration in multithreaded applications, the position within the
132 enumeration is a process-wide property shared by all threads. The set‐
133 grent() function can be used in a multithreaded application but resets
134 the enumeration position for all threads. If multiple threads inter‐
135 leave calls to getgrent_r(), the threads will enumerate disjoint sub‐
136 sets of the group database. Like their non-reentrant counterparts, get‐
137 grnam_r() and getgrgid_r() leave the enumeration position in an inde‐
138 terminate state.
139 group Structure
141 Group entries are represented by the struct group structure defined in
142 <grp.h>:
143 struct group {
145 char *gr_name; /* the name of the group */
146 char *gr_passwd; /* the encrypted group password */
147 gid_t gr_gid; /* the numerical group ID */
148 char **gr_mem; /* vector of pointers to member
149 names */
150 };
151
154 The getgrnam(), getgrnam_r(), getgrgid(), and getgrgid_r() functions
155 each return a pointer to a struct group if they successfully locate the
156 requested entry. They return a null pointer if either the requested
157 entry was not found or an error occurred. On error, errno is set to
158 indicate the error. The standard-conforming functions getgrnam_r() and
159 getgrgid_r() return 0 upon success or an error number in case of fail‐
160 ure.
161 The getgrent(), getgrent_r(), fgetgrent(), and fgetgrent_r() functions
164 each return a pointer to a struct group if they successfully enumerate
165 an entry; otherwise they return a null pointer on end-of-file or error.
166 On error, errno is set to indicate the error.
167 The getgrnam(), getgrgid(), getgrent(), and fgetgrent() functions use
170 thread-specific data storage, so returned data must be copied before a
171 subsequent call to any of these functions if the data are to be saved.
172 When the pointer returned by the reentrant functions getgrnam_r(), get‐
175 grgid_r(), getgrent_r(), and fgetgrent_r() is non-null, it is always
176 equal to the grp pointer that was supplied by the caller.
177 Applications wishing to check for error situations should set errno to
180 0 before calling getgrnam(), getgrnam_r(), getgrent(), getgrent_r()get‐
181 grgid(), getgrgid_r(), fgetgrent(), and fgetgrent_r(). If these func‐
182 tions return a null pointer and errno is non-zero, an error occurred.
183
185 The getgrent_r(), fgetgrent(), and fgetgrent_r() functions will fail
186 if:
187 EIO An I/O error has occurred.
189 ERANGE Insufficient storage was supplied by buffer and bufsize to
192 contain the data to be referenced by the resulting group
193 structure.
194 The getgrent_r() function will fail if:
198 EMFILE There are {OPEN_MAX} file descriptors currently open in the
200 calling process.
201 ENFILE The maximum allowable number of files is currently open in
204 the system.
205 The getgrnam(), getgrnam_r(), getgrgid(), getgrgid_r(), and getgrent()
209 functions may fail if:
210 EINTR A signal was caught during the operation.
212 EIO An I/O error has occurred.
215 EMFILE There are {OPEN_MAX} file descriptors currently open in the
218 calling process.
219 ENFILE The maximum allowable number of files is currently open in
222 the system.
223 The getgrnam_r() and getgrgid_r() functions may fail if:
227 ERANGE Insufficient storage was supplied by buffer and bufsize to
229 contain the data to be referenced by the resulting group
230 structure.
231
234 See attributes(5) for descriptions of the following attributes:
235 ┌─────────────────────────────┬─────────────────────────────────────────┐
240 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
241 ├─────────────────────────────┼─────────────────────────────────────────┤
242 │Interface Stability │See below. │
243 ├─────────────────────────────┼─────────────────────────────────────────┤
244 │MT-Level │See Reentrant Interfaces in DESCRIPTION. │
245 └─────────────────────────────┴─────────────────────────────────────────┘
246 The endgrent(), getgrent(), getgrgid(), getgrgid_r(), getgrnam(), get‐
249 grnam_r(), and setgrent() functions are Standard.
250
252 Intro(3), getpwnam(3C), group(4), nsswitch.conf(4), passwd(4),
253 attributes(5), standards(5)
254
256 When compiling multithreaded programs, see Intro(3).
257 Use of the enumeration interfaces getgrent() and getgrent_r() is dis‐
260 couraged; enumeration is supported for the group file, NIS, and NIS+,
261 but in general is not efficient and might not be supported for all
262 database sources. The semantics of enumeration are discussed further
263 in nsswitch.conf(4).
264 Previous releases allowed the use of ``+'' and ``-'' entries in
267 /etc/group to selectively include and exclude entries from NIS. The
268 primary usage of these entries is superseded by the name service
269 switch, so the ``+/-'' form might not be supported in future releases.
270 If required, the ``+/-'' functionality can still be obtained for NIS by
273 specifying compat as the source for group.
274 If the ``+/-'' functionality is required in conjunction with NIS+,
277 specify both compat as the source for group and nisplus as the source
278 for the pseudo-database group_compat. See group(4), and nss‐
279 witch.conf(4) for details.
280 Solaris 2.4 and earlier releases provided definitions of the getgr‐
283 nam_r() and getgrgid_r() functions as specified in POSIX.1c Draft 6.
284 The final POSIX.1c standard changed the interface for these functions.
285 Support for the Draft 6 interface is provided for compatibility only
286 and might not be supported in future releases. New applications and
287 libraries should use the standard-conforming interface.
288 For POSIX.1c-conforming applications, the _POSIX_PTHREAD_SEMANTICS and
291 _REENTRANT flags are automatically turned on by defining the
292 _POSIX_C_SOURCE flag with a value ≥199506L.
293SunOS 5.11 5 Apr 2004 getgrnam(3C)