Debian Codegraph @

upstream/debian-unstable/man3/getgrnam.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH getgrnam 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 getgrnam, getgrnam_r, getgrgid, getgrgid_r \- get group file entry
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/types.h>
16 .B #include <grp.h>
17 .P
18 .BI "struct group *getgrnam(const char *" name );
19 .BI "struct group *getgrgid(gid_t " gid );
20 .P
21 .BR "int getgrnam_r(" "size_t size;"
22 .BI " const char *restrict " name \
23 ", struct group *restrict " grp ,
24 .BI " char " buf "[restrict " size "], size_t " size ,
25 .BI " struct group **restrict " result );
26 .BR "int getgrgid_r(" "size_t size;"
27 .BI " gid_t " gid ", struct group *restrict " grp ,
28 .BI " char " buf "[restrict " size "], size_t " size ,
29 .BI " struct group **restrict " result );
30 .fi
31 .P
32 .RS -4
33 Feature Test Macro Requirements for glibc (see
34 .BR feature_test_macros (7)):
35 .RE
36 .P
37 .BR getgrnam_r (),
38 .BR getgrgid_r ():
39 .nf
40 _POSIX_C_SOURCE
41 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
42 .fi
43 .SH DESCRIPTION
44 The
45 .BR getgrnam ()
46 function returns a pointer to a structure containing
47 the broken-out fields of the record in the group database
48 (e.g., the local group file
49 .IR /etc/group ,
50 NIS, and LDAP)
51 that matches the group name
52 .IR name .
53 .P
54 The
55 .BR getgrgid ()
56 function returns a pointer to a structure containing
57 the broken-out fields of the record in the group database
58 that matches the group ID
59 .IR gid .
60 .P
61 The
62 .I group
63 structure is defined in
64 .I <grp.h>
65 as follows:
66 .P
67 .in +4n
68 .EX
69 struct group {
70 char *gr_name; /* group name */
71 char *gr_passwd; /* group password */
72 gid_t gr_gid; /* group ID */
73 char **gr_mem; /* NULL\-terminated array of pointers
74 to names of group members */
75 };
76 .EE
77 .in
78 .P
79 For more information about the fields of this structure, see
80 .BR group (5).
81 .P
82 The
83 .BR getgrnam_r ()
84 and
85 .BR getgrgid_r ()
86 functions obtain the same information as
87 .BR getgrnam ()
88 and
89 .BR getgrgid (),
90 but store the retrieved
91 .I group
92 structure
93 in the space pointed to by
94 .IR grp .
95 The string fields pointed to by the members of the
96 .I group
97 structure are stored in the buffer
98 .I buf
99 of size
100 .IR size .
101 A pointer to the result (in case of success) or NULL (in case no entry
102 was found or an error occurred) is stored in
103 .IR *result .
104 .P
105 The call
106 .P
107 .in +4n
108 .EX
109 sysconf(_SC_GETGR_R_SIZE_MAX)
110 .EE
111 .in
112 .P
113 returns either \-1, without changing
114 .IR errno ,
115 or an initial suggested size for
116 .IR buf .
117 (If this size is too small,
118 the call fails with
119 .BR ERANGE ,
120 in which case the caller can retry with a larger buffer.)
121 .SH RETURN VALUE
122 The
123 .BR getgrnam ()
124 and
125 .BR getgrgid ()
126 functions return a pointer to a
127 .I group
128 structure, or NULL if the matching entry
129 is not found or an error occurs.
130 If an error occurs,
131 .I errno
132 is set to indicate the error.
133 If one wants to check
134 .I errno
135 after the call, it should be set to zero before the call.
136 .P
137 The return value may point to a static area, and may be overwritten
138 by subsequent calls to
139 .BR getgrent (3),
140 .BR getgrgid (),
141 or
142 .BR getgrnam ().
143 (Do not pass the returned pointer to
144 .BR free (3).)
145 .P
146 On success,
147 .BR getgrnam_r ()
148 and
149 .BR getgrgid_r ()
150 return zero, and set
151 .I *result
152 to
153 .IR grp .
154 If no matching group record was found,
155 these functions return 0 and store NULL in
156 .IR *result .
157 In case of error, an error number is returned, and NULL is stored in
158 .IR *result .
159 .SH ERRORS
160 .TP
161 .BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ..."
162 The given
163 .I name
164 or
165 .I gid
166 was not found.
167 .TP
168 .B EINTR
169 A signal was caught;
170 see
171 .BR signal (7).
172 .TP
173 .B EIO
174 I/O error.
175 .TP
176 .B EMFILE
177 The per-process limit on the number of open file descriptors has been reached.
178 .TP
179 .B ENFILE
180 The system-wide limit on the total number of open files has been reached.
181 .TP
182 .B ENOMEM
183 .\" not in POSIX
184 Insufficient memory to allocate
185 .I group
186 structure.
187 .\" to allocate the group structure, or to allocate buffers
188 .TP
189 .B ERANGE
190 Insufficient buffer space supplied.
191 .SH FILES
192 .TP
193 .I /etc/group
194 local group database file
195 .SH ATTRIBUTES
196 For an explanation of the terms used in this section, see
197 .BR attributes (7).
198 .TS
199 allbox;
200 lb lb lbx
201 l l l.
202 Interface Attribute Value
203 T{
204 .na
205 .nh
206 .BR getgrnam ()
207 T} Thread safety T{
208 .na
209 .nh
210 MT-Unsafe race:grnam locale
211 T}
212 T{
213 .na
214 .nh
215 .BR getgrgid ()
216 T} Thread safety T{
217 .na
218 .nh
219 MT-Unsafe race:grgid locale
220 T}
221 T{
222 .na
223 .nh
224 .BR getgrnam_r (),
225 .BR getgrgid_r ()
226 T} Thread safety MT-Safe locale
227 .TE
228 .SH VERSIONS
229 The formulation given above under "RETURN VALUE" is from POSIX.1.
230 .\" POSIX.1-2001, POSIX.1-2008
231 It does not call "not found" an error, hence does not specify what value
232 .I errno
233 might have in this situation.
234 But that makes it impossible to recognize
235 errors.
236 One might argue that according to POSIX
237 .I errno
238 should be left unchanged if an entry is not found.
239 Experiments on various
240 UNIX-like systems show that lots of different values occur in this
241 situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others.
242 .\" more precisely:
243 .\" AIX 5.1 - gives ESRCH
244 .\" OSF1 4.0g - gives EWOULDBLOCK
245 .\" libc, glibc up to glibc 2.6, Irix 6.5 - give ENOENT
246 .\" since glibc 2.7 - give 0
247 .\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM
248 .\" SunOS 5.8 - gives EBADF
249 .\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0
250 .SH STANDARDS
251 POSIX.1-2008.
252 .SH HISTORY
253 POSIX.1-2001, SVr4, 4.3BSD.
254 .SH SEE ALSO
255 .BR endgrent (3),
256 .BR fgetgrent (3),
257 .BR getgrent (3),
258 .BR getpwnam (3),
259 .BR setgrent (3),
260 .BR group (5)