1GETGRNAM(3P) POSIX Programmer's Manual GETGRNAM(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 getgrnam, getgrnam_r — search group database for a name
14
16 #include <grp.h>
17 struct group *getgrnam(const char *name);
19 int getgrnam_r(const char *name, struct group *grp, char *buffer,
20 size_t bufsize, struct group **result);
21
23 The getgrnam() function shall search the group database for an entry
24 with a matching name.
25 The getgrnam() function need not be thread-safe.
27 The getgrnam_r() function shall update the group structure pointed to
29 by grp and store a pointer to that structure at the location pointed to
30 by result. The structure shall contain an entry from the group data‐
31 base with a matching name. Storage referenced by the group structure
32 is allocated from the memory provided with the buffer parameter, which
33 is bufsize bytes in size. A call to sysconf(_SC_GETGR_R_SIZE_MAX)
34 returns either −1 without changing errno or an initial value suggested
35 for the size of this buffer. A null pointer is returned at the loca‐
36 tion pointed to by result on error or if the requested entry is not
37 found.
38
40 The getgrnam() function shall return a pointer to a struct group with
41 the structure defined in <grp.h> with a matching entry if one is found.
42 The getgrnam() function shall return a null pointer if either the
43 requested entry was not found, or an error occurred. On error, errno
44 shall be set to indicate the error.
45 The application shall not modify the structure to which the return
47 value points, nor any storage areas pointed to by pointers within the
48 structure. The returned pointer, and pointers within the structure,
49 might be invalidated or the structure or the storage areas might be
50 overwritten by a subsequent call to getgrent(), getgrgid(), or getgr‐
51 nam().
52 The getgrnam_r() function shall return zero on success or if the
54 requested entry was not found and no error has occurred. If any error
55 has occurred, an error number shall be returned to indicate the error.
56
58 The getgrnam() and getgrnam_r() functions may fail if:
59 EIO An I/O error has occurred.
61 EINTR A signal was caught during getgrnam().
63 EMFILE All file descriptors available to the process are currently
65 open.
66 ENFILE The maximum allowable number of files is currently open in the
68 system.
69 The getgrnam_r() function may fail if:
71 ERANGE Insufficient storage was supplied via buffer and bufsize to con‐
73 tain the data to be referenced by the resulting group structure.
74 The following sections are informative.
76
78 Note that sysconf(_SC_GETGR_R_SIZE_MAX) may return −1 if there is no
79 hard limit on the size of the buffer needed to store all the groups
80 returned. This example shows how an application can allocate a buffer
81 of sufficient size to work with getgrnam_r().
82 long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX);
84 size_t len;
85 if (initlen == −1)
86 /* Default initial length. */
87 len = 1024;
88 else
89 len = (size_t) initlen;
90 struct group result;
91 struct group *resultp;
92 char *buffer = malloc(len);
93 if (buffer == NULL)
94 ...handle error...
95 int e;
96 while ((e = getgrnam_r("somegroup", &result, buffer, len, &resultp))
97 == ERANGE)
98 {
99 size_t newlen = 2 * len;
100 if (newlen < len)
101 ...handle error...
102 len = newlen;
103 char *newbuffer = realloc(buffer, len);
104 if (newbuffer == NULL)
105 ...handle error...
106 buffer = newbuffer;
107 }
108 if (e != 0)
109 ...handle error...
110 free (buffer);
111
113 Applications wishing to check for error situations should set errno to
114 0 before calling getgrnam(). If errno is set on return, an error
115 occurred.
116 The getgrnam_r() function is thread-safe and shall return values in a
118 user-supplied buffer instead of possibly using a static data area that
119 may be overwritten by each call.
120 Portable applications should take into account that it is usual for an
122 implementation to return −1 from sysconf() indicating that there is no
123 maximum for _SC_GETGR_R_SIZE_MAX.
124
126 None.
127
129 None.
130
132 endgrent(), getgrgid(), sysconf()
133 The Base Definitions volume of POSIX.1‐2008, <grp.h>, <sys_types.h>
135
137 Portions of this text are reprinted and reproduced in electronic form
138 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
139 -- Portable Operating System Interface (POSIX), The Open Group Base
140 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
141 cal and Electronics Engineers, Inc and The Open Group. (This is
142 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
143 event of any discrepancy between this version and the original IEEE and
144 The Open Group Standard, the original IEEE and The Open Group Standard
145 is the referee document. The original Standard can be obtained online
146 at http://www.unix.org/online.html .
147 Any typographical or formatting errors that appear in this page are
149 most likely to have been introduced during the conversion of the source
150 files to man page format. To report such errors, see https://www.ker‐
151 nel.org/doc/man-pages/reporting_bugs.html .
152IEEE/The Open Group 2013 GETGRNAM(3P)