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