1getgrnam(3C)             Standard C Library Functions             getgrnam(3C)
2
3
4

NAME

6       getgrnam,  getgrnam_r, getgrent, getgrent_r, getgrgid, getgrgid_r, set‐
7       grent, endgrent, fgetgrent, fgetgrent_r - group  database  entry  func‐
8       tions
9

SYNOPSIS

11       #include <grp.h>
12
13       struct group *getgrnam(const char *name);
14
15
16       struct group *getgrnam_r(const char *name, struct group *grp,
17            char *buffer, int bufsize);
18
19
20       struct group *getgrent(void);
21
22
23       struct group *getgrent_r(struct group *grp, char *buffer, int bufsize);
24
25
26       struct group *getgrgid(gid_t gid);
27
28
29       struct group *getgrgid_r(gid_t gid, struct group *grp, char *buffer,
30            int bufsize);
31
32
33       void setgrent(void);
34
35
36       void endgrent(void);
37
38
39       struct group *fgetgrent(FILE *f);
40
41
42       struct group *fgetgrent_r(FILE *f, struct group *grp, char *buffer,
43            int bufsize);
44
45
46   Standard comforming
47       cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]
48
49       int getgrnam_r(const char *name, struct group *grp, char *buffer,
50            size_t bufsize, struct group **result);
51
52
53       int getgrgid_r(gid_t gid, struct group *grp, char *buffer,
54            size_t bufsize, struct group **result);
55
56

DESCRIPTION

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
62
63       The  getgrnam()  function searches the group database for an entry with
64       the group name specified by the character string parameter name.
65
66
67       The getgrgid() function searches the group database for an  entry  with
68       the (numeric) group id specified by gid.
69
70
71       The  setgrent(),  getgrent(), and endgrent() functions are used to enu‐
72       merate group entries from the database.
73
74
75       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
80
81       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
87
88       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
93
94       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
98   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
104
105       The  parallel  functions  getgrnam_r(), getgrgid_r(), getgrent_r(), and
106       fgetgrent_r() provide reentrant interfaces for these operations.
107
108
109       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
116
117       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
130
131       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
140   group Structure
141       Group  entries are represented by the struct group structure defined in
142       <grp.h>:
143
144         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
152

RETURN VALUES

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
162
163       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
168
169       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
173
174       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
178
179       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

ERRORS

185       The getgrent_r(), fgetgrent(), and fgetgrent_r()  functions  will  fail
186       if:
187
188       EIO       An I/O error has occurred.
189
190
191       ERANGE    Insufficient  storage  was  supplied by buffer and bufsize to
192                 contain the data to be  referenced  by  the  resulting  group
193                 structure.
194
195
196
197       The getgrent_r() function will fail if:
198
199       EMFILE    There  are  {OPEN_MAX} file descriptors currently open in the
200                 calling process.
201
202
203       ENFILE    The maximum allowable number of files is  currently  open  in
204                 the system.
205
206
207
208       The  getgrnam(), getgrnam_r(), getgrgid(), getgrgid_r(), and getgrent()
209       functions may fail if:
210
211       EINTR     A signal was caught during the operation.
212
213
214       EIO       An I/O error has occurred.
215
216
217       EMFILE    There are {OPEN_MAX} file descriptors currently open  in  the
218                 calling process.
219
220
221       ENFILE    The  maximum  allowable  number of files is currently open in
222                 the system.
223
224
225
226       The getgrnam_r() and getgrgid_r() functions may fail if:
227
228       ERANGE    Insufficient storage was supplied by buffer  and  bufsize  to
229                 contain  the  data  to  be  referenced by the resulting group
230                 structure.
231
232

ATTRIBUTES

234       See attributes(5) for descriptions of the following attributes:
235
236
237
238
239       ┌─────────────────────────────┬─────────────────────────────────────────┐
240       │      ATTRIBUTE TYPE         │            ATTRIBUTE VALUE              │
241       ├─────────────────────────────┼─────────────────────────────────────────┤
242       │Interface Stability          │See below.                               │
243       ├─────────────────────────────┼─────────────────────────────────────────┤
244       │MT-Level                     │See Reentrant Interfaces in DESCRIPTION. │
245       └─────────────────────────────┴─────────────────────────────────────────┘
246
247
248       The endgrent(), getgrent(), getgrgid(), getgrgid_r(), getgrnam(),  get‐
249       grnam_r(), and setgrent() functions are Standard.
250

SEE ALSO

252       Intro(3),    getpwnam(3C),   group(4),   nsswitch.conf(4),   passwd(4),
253       attributes(5), standards(5)
254

NOTES

256       When compiling multithreaded programs, see Intro(3).
257
258
259       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
265
266       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
271
272       If required, the ``+/-'' functionality can still be obtained for NIS by
273       specifying compat as the source for group.
274
275
276       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
281
282       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
289
290       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.
293
294
295
296SunOS 5.11                        5 Apr 2004                      getgrnam(3C)
Impressum