]>
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. | |
11 | .\" | |
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. | |
19 | .\" | |
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 | .\" | |
32 | .TH GETPWNAM 3 1996-05-27 "GNU" "Linux Programmer's Manual" | |
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 | |
46 | .BI " char *" buf ", size_t " buflen ", struct passwd **" pwbufp ); | |
47 | .sp | |
48 | .BI "int getpwuid_r(uid_t " uid ", struct passwd *" pwbuf , | |
49 | .br | |
50 | .BI " char *" buf ", size_t " buflen ", struct passwd **" pwbufp ); | |
51 | .fi | |
52 | .SH DESCRIPTION | |
53 | The | |
63aa9df0 | 54 | .BR getpwnam () |
fea681da | 55 | function returns a pointer to a structure containing |
f936cf26 | 56 | the broken-out fields of the record in the password database |
f2738b39 MK |
57 | (e.g., the local password file |
58 | .IR /etc/passwd , | |
59 | NIS, and LDAP) | |
f936cf26 | 60 | that matches the user name |
fea681da MK |
61 | .IR name . |
62 | .PP | |
63 | The | |
63aa9df0 | 64 | .BR getpwuid () |
fea681da | 65 | function returns a pointer to a structure containing |
f2738b39 | 66 | the broken-out fields of the record in the password database |
f936cf26 | 67 | that matches the user ID |
fea681da MK |
68 | .IR uid . |
69 | .PP | |
70 | The | |
63aa9df0 | 71 | .BR getpwnam_r () |
fea681da | 72 | and |
63aa9df0 | 73 | .BR getpwuid_r () |
f2738b39 MK |
74 | functions obtain the same information, but store the retrieved |
75 | .I passwd | |
76 | structure in the space pointed to by | |
fea681da | 77 | .IR pwbuf . |
f2738b39 MK |
78 | This |
79 | .I passwd | |
80 | structure contains pointers to strings, and these strings | |
fea681da MK |
81 | are stored in the buffer |
82 | .I buf | |
83 | of size | |
84 | .IR buflen . | |
85 | A pointer to the result (in case of success) or NULL (in case no entry | |
86 | was found or an error occurred) is stored in | |
87 | .RI * pwbufp . | |
88 | .PP | |
89 | The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows: | |
90 | .sp | |
f2738b39 | 91 | .RS 0.25i |
fea681da MK |
92 | .nf |
93 | struct passwd { | |
f2738b39 MK |
94 | char *pw_name; /* user name */ |
95 | char *pw_passwd; /* user password */ | |
34c97781 MK |
96 | uid_t pw_uid; /* user ID */ |
97 | gid_t pw_gid; /* group ID */ | |
f2738b39 MK |
98 | char *pw_gecos; /* real name */ |
99 | char *pw_dir; /* home directory */ | |
100 | char *pw_shell; /* shell program */ | |
fea681da MK |
101 | }; |
102 | .fi | |
103 | .RE | |
104 | .PP | |
105 | The maximum needed size for | |
106 | .I buf | |
107 | can be found using | |
108 | .BR sysconf (3) | |
109 | with the _SC_GETPW_R_SIZE_MAX parameter. | |
110 | .SH "RETURN VALUE" | |
63aa9df0 | 111 | The \fBgetpwnam\fP() and \fBgetpwuid\fP() functions return a pointer to a |
f2738b39 MK |
112 | .I passwd |
113 | structure, or NULL if the matching entry is not found or | |
114 | an error occurs. | |
115 | If an error occurs, | |
fea681da | 116 | .I errno |
f2738b39 MK |
117 | is set appropriately. |
118 | If one wants to check | |
fea681da MK |
119 | .I errno |
120 | after the call, it should be set to zero before the call. | |
121 | .LP | |
122 | The return value may point to static area, and may be overwritten | |
123 | by subsequent calls to | |
63aa9df0 MK |
124 | .BR getpwent (), |
125 | .BR getpwnam (), | |
fea681da | 126 | or |
63aa9df0 | 127 | .BR getpwuid (). |
fea681da | 128 | .LP |
63aa9df0 | 129 | The \fBgetpwnam_r\fP() and \fBgetpwuid_r\fP() functions return |
f2738b39 | 130 | zero on success. In case of error, an error number is returned. |
fea681da MK |
131 | .SH ERRORS |
132 | .TP | |
133 | .BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ... " | |
134 | The given | |
135 | .I name | |
136 | or | |
137 | .I uid | |
138 | was not found. | |
139 | .TP | |
140 | .B EINTR | |
141 | A signal was caught. | |
142 | .TP | |
143 | .B EIO | |
144 | I/O error. | |
145 | .TP | |
146 | .B EMFILE | |
147 | The maximum number (OPEN_MAX) of files was open already in the calling process. | |
148 | .TP | |
149 | .B ENFILE | |
150 | The maximum number of files was open already in the system. | |
151 | .TP | |
152 | .B ENOMEM | |
f2738b39 | 153 | .\" not in POSIX |
fea681da MK |
154 | Insufficient memory to allocate passwd structure. |
155 | .\" This structure is static, allocated 0 or 1 times. No memory leak. (libc45) | |
156 | .TP | |
157 | .B ERANGE | |
158 | Insufficient buffer space supplied. | |
159 | .SH FILES | |
160 | .TP | |
161 | .I /etc/passwd | |
f2738b39 | 162 | local password database file |
fea681da MK |
163 | .fi |
164 | .SH "CONFORMING TO" | |
b14d4aa5 | 165 | SVID 3, 4.3BSD, POSIX 1003.1-2003 |
fea681da MK |
166 | .SH NOTES |
167 | The formulation given above under "RETURN VALUE" is from POSIX 1003.1-2001. | |
6b2fc294 | 168 | It does not call "not found" an error, and hence does not specify what value |
fea681da MK |
169 | .I errno |
170 | might have in this situation. But that makes it impossible to recognize | |
171 | errors. One might argue that according to POSIX | |
172 | .I errno | |
173 | should be left unchanged if an entry is not found. Experiments on various | |
6b2fc294 | 174 | Unix-like systems show that lots of different values occur in this |
fea681da MK |
175 | situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably others. |
176 | .\" more precisely: | |
177 | .\" AIX 5.1 - gives ESRCH | |
178 | .\" OSF1 4.0g - gives EWOULDBLOCK | |
179 | .\" libc, glibc, Irix 6.5 - give ENOENT | |
180 | .\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM | |
181 | .\" SunOS 5.8 - gives EBADF | |
182 | .\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 | |
6b2fc294 MK |
183 | |
184 | The | |
185 | .I pw_dir | |
186 | field contains the name of the initial working directory of the user. | |
187 | Login programs use the value of this field to initialize | |
188 | the HOME environment variable for the login shell. | |
189 | An application that wants to determine its user's home directory | |
190 | should inspect the value of HOME (rather than the value | |
191 | .IR getpwuid(getuid())->pw_dir ) | |
192 | since this allows the user to modify their notion of | |
193 | "the home directory" during a login session. | |
194 | To determine the (initial) home directory of another user, | |
195 | it is necessary to use | |
196 | .I getpwnam("username")->pw_dir | |
197 | or similar. | |
fea681da MK |
198 | .SH "SEE ALSO" |
199 | .BR endpwent (3), | |
200 | .BR fgetpwent (3), | |
201 | .BR getgrnam (3), | |
202 | .BR getpw (3), | |
203 | .BR getpwent (3), | |
204 | .BR putpwent (3), | |
205 | .BR setpwent (3), | |
206 | .BR passwd (5) |