Debian Codegraph @

upstream/debian-trixie/man3/getpwnam.3

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