Debian Codegraph @

upstream/mageia-cauldron/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.17"
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 FILES
195 .TP
196 .I /etc/passwd
197 local password database file
198 .SH ATTRIBUTES
199 For an explanation of the terms used in this section, see
200 .BR attributes (7).
201 .TS
202 allbox;
203 lb lb lbx
204 l l l.
205 Interface Attribute Value
206 T{
207 .na
208 .nh
209 .BR getpwnam ()
210 T} Thread safety T{
211 .na
212 .nh
213 MT-Unsafe race:pwnam locale
214 T}
215 T{
216 .na
217 .nh
218 .BR getpwuid ()
219 T} Thread safety T{
220 .na
221 .nh
222 MT-Unsafe race:pwuid locale
223 T}
224 T{
225 .na
226 .nh
227 .BR getpwnam_r (),
228 .BR getpwuid_r ()
229 T} Thread safety T{
230 .na
231 .nh
232 MT-Safe locale
233 T}
234 .TE
235 .SH VERSIONS
236 The
237 .I pw_gecos
238 field is not specified in POSIX, but is present on most implementations.
239 .SH STANDARDS
240 POSIX.1-2008.
241 .SH HISTORY
242 POSIX.1-2001, SVr4, 4.3BSD.
243 .SH NOTES
244 The formulation given above under "RETURN VALUE" is from POSIX.1-2001.
245 It does not call "not found" an error, and hence does not specify what value
246 .I errno
247 might have in this situation.
248 But that makes it impossible to recognize
249 errors.
250 One might argue that according to POSIX
251 .I errno
252 should be left unchanged if an entry is not found.
253 Experiments on various
254 UNIX-like systems show that lots of different values occur in this
255 situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others.
256 .\" more precisely:
257 .\" AIX 5.1 - gives ESRCH
258 .\" OSF1 4.0g - gives EWOULDBLOCK
259 .\" libc, glibc up to glibc 2.6, Irix 6.5 - give ENOENT
260 .\" since glibc 2.7 - give 0
261 .\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM
262 .\" SunOS 5.8 - gives EBADF
263 .\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0
264 .P
265 The
266 .I pw_dir
267 field contains the name of the initial working directory of the user.
268 Login programs use the value of this field to initialize the
269 .B HOME
270 environment variable for the login shell.
271 An application that wants to determine its user's home directory
272 should inspect the value of
273 .B HOME
274 (rather than the value
275 .IR getpwuid(getuid())\->pw_dir )
276 since this allows the user to modify their notion of
277 "the home directory" during a login session.
278 To determine the (initial) home directory of another user,
279 it is necessary to use
280 .I getpwnam("username")\->pw_dir
281 or similar.
282 .SH EXAMPLES
283 The program below demonstrates the use of
284 .BR getpwnam_r ()
285 to find the full username and user ID for the username
286 supplied as a command-line argument.
287 .P
288 .\" SRC BEGIN (getpwnam.c)
289 .EX
290 #include <errno.h>
291 #include <pwd.h>
292 #include <stdint.h>
293 #include <stdio.h>
294 #include <stdlib.h>
295 #include <unistd.h>
296 \&
297 int
298 main(int argc, char *argv[])
299 {
300 struct passwd pwd;
301 struct passwd *result;
302 char *buf;
303 long bufsize;
304 int s;
305 \&
306 if (argc != 2) {
307 fprintf(stderr, "Usage: %s username\[rs]n", argv[0]);
308 exit(EXIT_FAILURE);
309 }
310 \&
311 bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
312 if (bufsize == \-1) /* Value was indeterminate */
313 bufsize = 16384; /* Should be more than enough */
314 \&
315 buf = malloc(bufsize);
316 if (buf == NULL) {
317 perror("malloc");
318 exit(EXIT_FAILURE);
319 }
320 \&
321 s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
322 if (result == NULL) {
323 if (s == 0)
324 printf("Not found\[rs]n");
325 else {
326 errno = s;
327 perror("getpwnam_r");
328 }
329 exit(EXIT_FAILURE);
330 }
331 \&
332 printf("Name: %s; UID: %jd\[rs]n", pwd.pw_gecos,
333 (intmax_t) pwd.pw_uid);
334 exit(EXIT_SUCCESS);
335 }
336 .EE
337 .\" SRC END
338 .SH SEE ALSO
339 .BR endpwent (3),
340 .BR fgetpwent (3),
341 .BR getgrnam (3),
342 .BR getpw (3),
343 .BR getpwent (3),
344 .BR getspnam (3),
345 .BR putpwent (3),
346 .BR setpwent (3),
347 .BR passwd (5)