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