1.\"	$OpenBSD: getpwnam.3,v 1.13 2018/08/21 20:20:04 millert Exp $
2.\"
3.\" Copyright (c) 1988, 1991, 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.Dd $Mdocdate: August 21 2018 $
31.Dt GETPWNAM 3
32.Os
33.Sh NAME
34.Nm getpwnam ,
35.Nm getpwuid ,
36.Nm getpwnam_r ,
37.Nm getpwuid_r ,
38.Nm getpwnam_shadow ,
39.Nm getpwuid_shadow ,
40.Nm setpassent
41.Nd password database operations
42.Sh SYNOPSIS
43.In pwd.h
44.Ft struct passwd *
45.Fn getpwnam "const char *login"
46.Ft struct passwd *
47.Fn getpwuid "uid_t uid"
48.Ft int
49.Fn getpwnam_r "const char *login" "struct passwd *pwstore" "char *buf" "size_t bufsize" "struct passwd **result"
50.Ft int
51.Fn getpwuid_r "uid_t uid" "struct passwd *pwstore" "char *buf" "size_t bufsize" "struct passwd **result"
52.Ft struct passwd *
53.Fn getpwnam_shadow "const char *login"
54.Ft struct passwd *
55.Fn getpwuid_shadow "uid_t uid"
56.Ft int
57.Fn setpassent "int stayopen"
58.Sh DESCRIPTION
59These functions operate on the password database file which is described in
60.Xr passwd 5 .
61Each entry in the database is defined by the structure
62.Li struct passwd
63found in the include file
64.In pwd.h :
65.Bd -literal -offset indent
66struct passwd {
67	char	*pw_name;	/* user name */
68	char	*pw_passwd;	/* encrypted password */
69	uid_t	pw_uid;		/* user uid */
70	gid_t	pw_gid;		/* user gid */
71	time_t	pw_change;	/* password change time */
72	char	*pw_class;	/* user access class */
73	char	*pw_gecos;	/* Honeywell login info */
74	char	*pw_dir;	/* home directory */
75	char	*pw_shell;	/* default shell */
76	time_t	pw_expire;	/* account expiration */
77};
78.Ed
79.Pp
80The functions
81.Fn getpwnam
82and
83.Fn getpwuid
84search the password database for the given login name or user ID,
85respectively, always returning the first one encountered.
86.Pp
87The
88.Fn getpwnam_r
89and
90.Fn getpwuid_r
91functions both update the passwd structure pointed to by
92.Fa pwstore
93and store a pointer to that structure at the location pointed to by
94.Fa result .
95The structure is filled with an entry from the password database with a
96matching
97.Fa name
98or
99.Fa uid .
100Storage referenced by the passwd structure will be allocated from
101the memory provided with the
102.Fa buf
103parameter, which is
104.Fa bufsiz
105characters in size.
106The maximum size needed for this buffer can be determined with
107.Fn sysconf _SC_GETPW_R_SIZE_MAX .
108.Pp
109.Fn setpassent
110accomplishes two purposes.
111First, it causes
112.Xr getpwent 3
113to
114.Dq rewind
115to the beginning of the database.
116Additionally, if
117.Fa stayopen
118is non-zero, file descriptors are left open, significantly speeding
119up subsequent accesses for the lookup routines.
120These file descriptors can be closed by a call to
121.Xr endpwent 3 .
122.Pp
123It is dangerous for long-running programs to keep the file descriptors
124open as the database will become out of date if it is updated while the
125program is running.
126However the file descriptors are automatically closed when
127.Xr execve 2
128is called.
129.Pp
130These routines have been written to
131.Dq shadow
132the password file, that is,
133allow only certain programs to have access to the encrypted password.
134The default functions will not return the true encrypted password, but
135instead only the string
136.Ql * .
137If the process which calls them has an effective UID of 0 or has the
138.Dq _shadow
139group in its group vector, and wishes to access the encrypted password,
140it should use the
141.Fn getpwnam_shadow
142and
143.Fn getpwuid_shadow
144functions.
145.Ss YP support
146If YP is active, the functions
147.Fn getpwnam
148and
149.Fn getpwnam_r
150also use the
151.Pa master.passwd.byname
152YP map (if available) or the
153.Pa passwd.byname
154YP map; and the functions
155.Fn getpwuid
156and
157.Fn getpwuid_r
158also use the
159.Pa master.passwd.byuid
160YP map (if available) or the
161.Pa passwd.byuid
162YP map.
163This is in addition to the passwd file,
164and respects the order of both normal and YP
165entries in the passwd file.
166.Sh RETURN VALUES
167The functions
168.Fn getpwnam ,
169.Fn getpwnam_shadow ,
170.Fn getpwuid ,
171and
172.Fn getpwuid_shadow
173return a pointer to a passwd structure if a match is found or a null
174pointer if no match is found or an error occurs.
175Subsequent calls to
176.Fn getpwent ,
177.Fn getpwnam ,
178.Fn getpwnam_shadow ,
179.Fn getpwuid
180or
181.Fn getpwuid_shadow
182may invalidate the returned pointer or overwrite the contents
183of the passwd structure it points to.
184.Pp
185The functions
186.Fn getpwnam_r
187and
188.Fn getpwuid_r
189update
190.Fa result
191to point to
192.Fa pwstore
193if a match is found or set it to
194.Dv NULL
195if no match is found or an error occurs.
196They return 0 on success, even if no match is found,
197or an error number if an error occurs; see
198.Sx ERRORS .
199.Pp
200The
201.Fn setpassent
202function returns 0 on failure or 1 on success.
203.Sh FILES
204.Bl -tag -width /etc/master.passwd -compact
205.It Pa /etc/pwd.db
206insecure password database file
207.It Pa /etc/spwd.db
208secure password database file
209.It Pa /etc/master.passwd
210current password file
211.It Pa /etc/passwd
212legacy password file
213.El
214.Sh ERRORS
215The
216.Fn getpwnam_r
217and
218.Fn getpwuid_r
219functions may fail if:
220.Bl -tag -width Er
221.It Bq Er ERANGE
222The storage supplied via
223.Fa buf
224and
225.Fa bufsize
226is too small and cannot contain all the strings to be returned in
227.Fa pwstore .
228.El
229.Pp
230The
231.Fn getpwnam ,
232.Fn getpwnam_r ,
233.Fn getpwuid ,
234and
235.Fn getpwuid_r
236functions may also fail for any of the errors specified for
237.Xr dbopen 3
238and its
239.Fn get
240routine.
241.Pp
242If YP is active, they may also fail due to errors caused by the YP
243subsystem.
244.Sh SEE ALSO
245.Xr getlogin 2 ,
246.Xr getgrent 3 ,
247.Xr getgrouplist 3 ,
248.Xr getpwent 3 ,
249.Xr pw_dup 3 ,
250.Xr sysconf 3 ,
251.Xr passwd 5 ,
252.Xr Makefile.yp 8 ,
253.Xr pwd_mkdb 8 ,
254.Xr vipw 8 ,
255.Xr yp 8
256.Sh STANDARDS
257The
258.Fn getpwnam ,
259.Fn getpwnam_r ,
260.Fn getpwuid ,
261and
262.Fn getpwuid_r
263functions are compliant with the
264.St -p1003.1-2008
265specification.
266.Pp
267.Sx YP support
268and the
269.Fn setpassent
270function are extensions to that specification.
271.Sh HISTORY
272A predecessor to
273.Fn getpwuid ,
274.Fn getpw ,
275first appeared in
276.At v4 .
277The
278.Fn getpwnam
279and
280.Fn getpwuid
281functions appeared in
282.At v7 ,
283.Fn setpassent
284in
285.Bx 4.3 Reno ,
286and
287.Fn getpwnam_shadow
288and
289.Fn getpwuid_shadow
290in
291.Ox 5.9 .
292