]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
c13182ef | 11 | .\" |
fea681da MK |
12 | .\" Since the Linux kernel and libraries are constantly changing, this |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" References consulted: | |
24 | .\" Linux libc source code | |
6b2fc294 | 25 | .\" Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, 1991) |
fea681da MK |
26 | .\" 386BSD man pages |
27 | .\" | |
28 | .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) | |
29 | .\" Modified 1996-05-27 by Martin Schulze (joey@linux.de) | |
30 | .\" Modified 2003-11-15 by aeb | |
31 | .\" | |
cc4615cc | 32 | .TH GETPWNAM 3 2007-07-26 "GNU" "Linux Programmer's Manual" |
fea681da MK |
33 | .SH NAME |
34 | getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry | |
35 | .SH SYNOPSIS | |
36 | .nf | |
37 | .B #include <sys/types.h> | |
38 | .B #include <pwd.h> | |
39 | .sp | |
40 | .BI "struct passwd *getpwnam(const char *" name ); | |
41 | .sp | |
42 | .BI "struct passwd *getpwuid(uid_t " uid ); | |
43 | .sp | |
44 | .BI "int getpwnam_r(const char *" name ", struct passwd *" pwbuf , | |
45 | .br | |
62218dc0 | 46 | .BI " char *" buf ", size_t " buflen ", struct passwd **" pwbufp ); |
fea681da MK |
47 | .sp |
48 | .BI "int getpwuid_r(uid_t " uid ", struct passwd *" pwbuf , | |
49 | .br | |
62218dc0 | 50 | .BI " char *" buf ", size_t " buflen ", struct passwd **" pwbufp ); |
fea681da | 51 | .fi |
cc4615cc MK |
52 | .sp |
53 | .in -4n | |
54 | Feature Test Macro Requirements for glibc (see | |
55 | .BR feature_test_macros (7)): | |
56 | .in | |
57 | .sp | |
58 | .ad l | |
59 | .BR getpwnam_r (), | |
60 | .BR getpwuid_r (): | |
61 | _POSIX_C_SOURCE || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE | |
62 | .ad b | |
fea681da MK |
63 | .SH DESCRIPTION |
64 | The | |
63aa9df0 | 65 | .BR getpwnam () |
fea681da | 66 | function returns a pointer to a structure containing |
f936cf26 | 67 | the broken-out fields of the record in the password database |
c13182ef | 68 | (e.g., the local password file |
f2738b39 MK |
69 | .IR /etc/passwd , |
70 | NIS, and LDAP) | |
f936cf26 | 71 | that matches the user name |
fea681da MK |
72 | .IR name . |
73 | .PP | |
74 | The | |
63aa9df0 | 75 | .BR getpwuid () |
fea681da | 76 | function returns a pointer to a structure containing |
f2738b39 | 77 | the broken-out fields of the record in the password database |
f936cf26 | 78 | that matches the user ID |
fea681da MK |
79 | .IR uid . |
80 | .PP | |
81 | The | |
63aa9df0 | 82 | .BR getpwnam_r () |
fea681da | 83 | and |
63aa9df0 | 84 | .BR getpwuid_r () |
f2738b39 MK |
85 | functions obtain the same information, but store the retrieved |
86 | .I passwd | |
87 | structure in the space pointed to by | |
fea681da | 88 | .IR pwbuf . |
f2738b39 MK |
89 | This |
90 | .I passwd | |
91 | structure contains pointers to strings, and these strings | |
fea681da MK |
92 | are stored in the buffer |
93 | .I buf | |
94 | of size | |
95 | .IR buflen . | |
96 | A pointer to the result (in case of success) or NULL (in case no entry | |
97 | was found or an error occurred) is stored in | |
bd9b2a9c | 98 | .IR *pwbufp . |
fea681da MK |
99 | .PP |
100 | The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows: | |
101 | .sp | |
bd191423 | 102 | .in +4n |
fea681da MK |
103 | .nf |
104 | struct passwd { | |
f2738b39 MK |
105 | char *pw_name; /* user name */ |
106 | char *pw_passwd; /* user password */ | |
34c97781 MK |
107 | uid_t pw_uid; /* user ID */ |
108 | gid_t pw_gid; /* group ID */ | |
f2738b39 MK |
109 | char *pw_gecos; /* real name */ |
110 | char *pw_dir; /* home directory */ | |
111 | char *pw_shell; /* shell program */ | |
fea681da MK |
112 | }; |
113 | .fi | |
bd191423 | 114 | .in |
fea681da MK |
115 | .PP |
116 | The maximum needed size for | |
117 | .I buf | |
118 | can be found using | |
119 | .BR sysconf (3) | |
2f0af33b | 120 | with the |
0daa9e92 | 121 | .B _SC_GETPW_R_SIZE_MAX |
2f0af33b | 122 | parameter. |
fea681da | 123 | .SH "RETURN VALUE" |
60a90ecd MK |
124 | The |
125 | .BR getpwnam () | |
126 | and | |
127 | .BR getpwuid () | |
128 | functions return a pointer to a | |
f2738b39 MK |
129 | .I passwd |
130 | structure, or NULL if the matching entry is not found or | |
131 | an error occurs. | |
132 | If an error occurs, | |
fea681da | 133 | .I errno |
f2738b39 MK |
134 | is set appropriately. |
135 | If one wants to check | |
fea681da MK |
136 | .I errno |
137 | after the call, it should be set to zero before the call. | |
138 | .LP | |
139 | The return value may point to static area, and may be overwritten | |
140 | by subsequent calls to | |
3a72373c | 141 | .BR getpwent (3), |
63aa9df0 | 142 | .BR getpwnam (), |
fea681da | 143 | or |
63aa9df0 | 144 | .BR getpwuid (). |
fea681da | 145 | .LP |
988db661 | 146 | The |
60a90ecd MK |
147 | .BR getpwnam_r () |
148 | and | |
149 | .BR getpwuid_r () | |
150 | functions return | |
c13182ef MK |
151 | zero on success. |
152 | In case of error, an error number is returned. | |
fea681da MK |
153 | .SH ERRORS |
154 | .TP | |
155 | .BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ... " | |
156 | The given | |
157 | .I name | |
158 | or | |
159 | .I uid | |
160 | was not found. | |
161 | .TP | |
162 | .B EINTR | |
163 | A signal was caught. | |
164 | .TP | |
165 | .B EIO | |
166 | I/O error. | |
167 | .TP | |
168 | .B EMFILE | |
2f0af33b MK |
169 | The maximum number |
170 | .RB ( OPEN_MAX ) | |
171 | of files was open already in the calling process. | |
fea681da MK |
172 | .TP |
173 | .B ENFILE | |
174 | The maximum number of files was open already in the system. | |
175 | .TP | |
176 | .B ENOMEM | |
f2738b39 | 177 | .\" not in POSIX |
fea681da MK |
178 | Insufficient memory to allocate passwd structure. |
179 | .\" This structure is static, allocated 0 or 1 times. No memory leak. (libc45) | |
180 | .TP | |
181 | .B ERANGE | |
182 | Insufficient buffer space supplied. | |
183 | .SH FILES | |
184 | .TP | |
185 | .I /etc/passwd | |
f2738b39 | 186 | local password database file |
fea681da | 187 | .SH "CONFORMING TO" |
68e1685c | 188 | SVr4, 4.3BSD, POSIX.1-2001 |
fea681da | 189 | .SH NOTES |
68e1685c | 190 | The formulation given above under "RETURN VALUE" is from POSIX.1-2001. |
6b2fc294 | 191 | It does not call "not found" an error, and hence does not specify what value |
fea681da | 192 | .I errno |
c13182ef MK |
193 | might have in this situation. |
194 | But that makes it impossible to recognize | |
195 | errors. | |
196 | One might argue that according to POSIX | |
fea681da | 197 | .I errno |
c13182ef MK |
198 | should be left unchanged if an entry is not found. |
199 | Experiments on various | |
6b2fc294 | 200 | Unix-like systems show that lots of different values occur in this |
fea681da MK |
201 | situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably others. |
202 | .\" more precisely: | |
203 | .\" AIX 5.1 - gives ESRCH | |
204 | .\" OSF1 4.0g - gives EWOULDBLOCK | |
205 | .\" libc, glibc, Irix 6.5 - give ENOENT | |
206 | .\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM | |
207 | .\" SunOS 5.8 - gives EBADF | |
208 | .\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 | |
6b2fc294 | 209 | |
c13182ef MK |
210 | The |
211 | .I pw_dir | |
212 | field contains the name of the initial working directory of the user. | |
2f0af33b MK |
213 | Login programs use the value of this field to initialize the |
214 | .B HOME | |
215 | environment variable for the login shell. | |
6b2fc294 | 216 | An application that wants to determine its user's home directory |
2f0af33b MK |
217 | should inspect the value of |
218 | .B HOME | |
219 | (rather than the value | |
94e9d9fe | 220 | .IR getpwuid(getuid())\->pw_dir ) |
6b2fc294 MK |
221 | since this allows the user to modify their notion of |
222 | "the home directory" during a login session. | |
223 | To determine the (initial) home directory of another user, | |
c13182ef | 224 | it is necessary to use |
94e9d9fe | 225 | .I getpwnam("username")\->pw_dir |
6b2fc294 | 226 | or similar. |
fea681da MK |
227 | .SH "SEE ALSO" |
228 | .BR endpwent (3), | |
229 | .BR fgetpwent (3), | |
230 | .BR getgrnam (3), | |
231 | .BR getpw (3), | |
232 | .BR getpwent (3), | |
233 | .BR putpwent (3), | |
234 | .BR setpwent (3), | |
235 | .BR passwd (5) |