Debian Codegraph @

upstream/debian-unstable/man3/getpwnam.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 getpwnam 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password 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 <pwd.h>
17 .P
18 .BI "struct passwd *getpwnam(const char *" name );
19 .BI "struct passwd *getpwuid(uid_t " uid );
20 .P
21 .BR "int getpwnam_r(" "size_t size;"
22 .BI " const char *restrict " name ,
23 .BI " struct passwd *restrict " pwd ,
24 .BI " char " buf "[restrict " size "], size_t " size ,
25 .BI " struct passwd **restrict " result );
26 .BR "int getpwuid_r(" "size_t size;"
27 .BI " uid_t " uid ,
28 .BI " struct passwd *restrict " pwd ,
29 .BI " char " buf "[restrict " size "], size_t " size ,
30 .BI " struct passwd **restrict " result );
31 .fi
32 .P
33 .RS -4
34 Feature Test Macro Requirements for glibc (see
35 .BR feature_test_macros (7)):
36 .RE
37 .P
38 .BR getpwnam_r (),
39 .BR getpwuid_r ():
40 .nf
41 _POSIX_C_SOURCE
42 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
43 .fi
44 .SH DESCRIPTION
45 The
46 .BR getpwnam ()
47 function returns a pointer to a structure containing
48 the broken-out fields of the record in the password database
49 (e.g., the local password file
50 .IR /etc/passwd ,
51 NIS, and LDAP)
52 that matches the username
53 .IR name .
54 .P
55 The
56 .BR getpwuid ()
57 function returns a pointer to a structure containing
58 the broken-out fields of the record in the password database
59 that matches the user ID
60 .IR uid .
61 .P
62 The
63 .I passwd
64 structure is defined in
65 .I <pwd.h>
66 as follows:
67 .P
68 .in +4n
69 .EX
70 struct passwd {
71 char *pw_name; /* username */
72 char *pw_passwd; /* user password */
73 uid_t pw_uid; /* user ID */
74 gid_t pw_gid; /* group ID */
75 char *pw_gecos; /* user information */
76 char *pw_dir; /* home directory */
77 char *pw_shell; /* shell program */
78 };
79 .EE
80 .in
81 .P
82 See
83 .BR passwd (5)
84 for more information about these fields.
85 .P
86 The
87 .BR getpwnam_r ()
88 and
89 .BR getpwuid_r ()
90 functions obtain the same information as
91 .BR getpwnam ()
92 and
93 .BR getpwuid (),
94 but store the retrieved
95 .I passwd
96 structure in the space pointed to by
97 .IR pwd .
98 The string fields pointed to by the members of the
99 .I passwd
100 structure are stored in the buffer
101 .I buf
102 of size
103 .IR size .
104 A pointer to the result (in case of success) or NULL (in case no entry
105 was found or an error occurred) is stored in
106 .IR *result .
107 .P
108 The call
109 .P
110 .in +4n
111 .EX
112 sysconf(_SC_GETPW_R_SIZE_MAX)
113 .EE
114 .in
115 .P
116 returns either \-1, without changing
117 .IR errno ,
118 or an initial suggested size for
119 .IR buf .
120 (If this size is too small,
121 the call fails with
122 .BR ERANGE ,
123 in which case the caller can retry with a larger buffer.)
124 .SH RETURN VALUE
125 The
126 .BR getpwnam ()
127 and
128 .BR getpwuid ()
129 functions return a pointer to a
130 .I passwd
131 structure, or NULL if the matching entry is not found or
132 an error occurs.
133 If an error occurs,
134 .I errno
135 is set to indicate the error.
136 If one wants to check
137 .I errno
138 after the call, it should be set to zero before the call.
139 .P
140 The return value may point to a static area, and may be overwritten
141 by subsequent calls to
142 .BR getpwent (3),
143 .BR getpwnam (),
144 or
145 .BR getpwuid ().
146 (Do not pass the returned pointer to
147 .BR free (3).)
148 .P
149 On success,
150 .BR getpwnam_r ()
151 and
152 .BR getpwuid_r ()
153 return zero, and set
154 .I *result
155 to
156 .IR pwd .
157 If no matching password record was found,
158 these functions return 0 and store NULL in
159 .IR *result .
160 In case of error, an error number is returned, and NULL is stored in
161 .IR *result .
162 .SH ERRORS
163 .TP
164 .BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ..."
165 The given
166 .I name
167 or
168 .I uid
169 was not found.
170 .TP
171 .B EINTR
172 A signal was caught;
173 see
174 .BR signal (7).
175 .TP
176 .B EIO
177 I/O error.
178 .TP
179 .B EMFILE
180 The per-process limit on the number of open file descriptors has been reached.
181 .TP
182 .B ENFILE
183 The system-wide limit on the total number of open files has been reached.
184 .TP
185 .B ENOMEM
186 .\" not in POSIX
187 Insufficient memory to allocate
188 .I passwd
189 structure.
190 .\" This structure is static, allocated 0 or 1 times. No memory leak. (libc45)
191 .TP
192 .B ERANGE
193 Insufficient buffer space supplied.
194 .SH NOTE
195 The user password database mostly refers to \fI/etc/passwd\fP.
196 However, with recent systems it also refers to network wide databases
197 using NIS, LDAP and other local files as configured in
198 \fI/etc/nsswitch.conf\fP.
199 .SH FILES
200 .TP
201 .I /etc/passwd
202 local password database file
203 .TP
204 .I /etc/nsswitch.conf
205 System Databases and Name Service Switch configuration file
206 .SH ATTRIBUTES
207 For an explanation of the terms used in this section, see
208 .BR attributes (7).
209 .TS
210 allbox;
211 lb lb lbx
212 l l l.
213 Interface Attribute Value
214 T{
215 .na
216 .nh
217 .BR getpwnam ()
218 T} Thread safety T{
219 .na
220 .nh
221 MT-Unsafe race:pwnam locale
222 T}
223 T{
224 .na
225 .nh
226 .BR getpwuid ()
227 T} Thread safety T{
228 .na
229 .nh
230 MT-Unsafe race:pwuid locale
231 T}
232 T{
233 .na
234 .nh
235 .BR getpwnam_r (),
236 .BR getpwuid_r ()
237 T} Thread safety T{
238 .na
239 .nh
240 MT-Safe locale
241 T}
242 .TE
243 .SH VERSIONS
244 The
245 .I pw_gecos
246 field is not specified in POSIX, but is present on most implementations.
247 .SH STANDARDS
248 POSIX.1-2008.
249 .SH HISTORY
250 POSIX.1-2001, SVr4, 4.3BSD.
251 .SH NOTES
252 The formulation given above under "RETURN VALUE" is from POSIX.1-2001.
253 It does not call "not found" an error, and hence does not specify what value
254 .I errno
255 might have in this situation.
256 But that makes it impossible to recognize
257 errors.
258 One might argue that according to POSIX
259 .I errno
260 should be left unchanged if an entry is not found.
261 Experiments on various
262 UNIX-like systems show that lots of different values occur in this
263 situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others.
264 .\" more precisely:
265 .\" AIX 5.1 - gives ESRCH
266 .\" OSF1 4.0g - gives EWOULDBLOCK
267 .\" libc, glibc up to glibc 2.6, Irix 6.5 - give ENOENT
268 .\" since glibc 2.7 - give 0
269 .\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM
270 .\" SunOS 5.8 - gives EBADF
271 .\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0
272 .P
273 The
274 .I pw_dir
275 field contains the name of the initial working directory of the user.
276 Login programs use the value of this field to initialize the
277 .B HOME
278 environment variable for the login shell.
279 An application that wants to determine its user's home directory
280 should inspect the value of
281 .B HOME
282 (rather than the value
283 .IR getpwuid(getuid())\->pw_dir )
284 since this allows the user to modify their notion of
285 "the home directory" during a login session.
286 To determine the (initial) home directory of another user,
287 it is necessary to use
288 .I getpwnam("username")\->pw_dir
289 or similar.
290 .SH EXAMPLES
291 The program below demonstrates the use of
292 .BR getpwnam_r ()
293 to find the full username and user ID for the username
294 supplied as a command-line argument.
295 .P
296 .\" SRC BEGIN (getpwnam.c)
297 .EX
298 #include <errno.h>
299 #include <pwd.h>
300 #include <stdint.h>
301 #include <stdio.h>
302 #include <stdlib.h>
303 #include <unistd.h>
304 \&
305 int
306 main(int argc, char *argv[])
307 {
308 struct passwd pwd;
309 struct passwd *result;
310 char *buf;
311 long bufsize;
312 int s;
313 \&
314 if (argc != 2) {
315 fprintf(stderr, "Usage: %s username\[rs]n", argv[0]);
316 exit(EXIT_FAILURE);
317 }
318 \&
319 bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
320 if (bufsize == \-1) /* Value was indeterminate */
321 bufsize = 16384; /* Should be more than enough */
322 \&
323 buf = malloc(bufsize);
324 if (buf == NULL) {
325 perror("malloc");
326 exit(EXIT_FAILURE);
327 }
328 \&
329 s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
330 if (result == NULL) {
331 if (s == 0)
332 printf("Not found\[rs]n");
333 else {
334 errno = s;
335 perror("getpwnam_r");
336 }
337 exit(EXIT_FAILURE);
338 }
339 \&
340 printf("Name: %s; UID: %jd\[rs]n", pwd.pw_gecos,
341 (intmax_t) pwd.pw_uid);
342 exit(EXIT_SUCCESS);
343 }
344 .EE
345 .\" SRC END
346 .SH SEE ALSO
347 .BR endpwent (3),
348 .BR fgetpwent (3),
349 .BR getgrnam (3),
350 .BR getpw (3),
351 .BR getpwent (3),
352 .BR getspnam (3),
353 .BR putpwent (3),
354 .BR setpwent (3),
355 .BR nsswitch.conf (5),
356 .BR passwd (5)