xref: /dragonfly/lib/libc/gen/getpwent.3 (revision 984263bc) 
1.\" Copyright (c) 1988, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\"    must display the following acknowledgement:
14.\"	This product includes software developed by the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     From: @(#)getpwent.3	8.2 (Berkeley) 12/11/93
33.\" $FreeBSD: src/lib/libc/gen/getpwent.3,v 1.11.2.5 2002/02/01 15:51:16 ru Exp $
34.\"
35.Dd September 20, 1994
36.Dt GETPWENT 3
37.Os
38.Sh NAME
39.Nm getpwent ,
40.Nm getpwnam ,
41.Nm getpwuid ,
42.Nm setpassent ,
43.Nm setpwent ,
44.Nm endpwent
45.Nd password database operations
46.Sh LIBRARY
47.Lb libc
48.Sh SYNOPSIS
49.In sys/types.h
50.In pwd.h
51.Ft struct passwd *
52.Fn getpwent void
53.Ft struct passwd *
54.Fn getpwnam "const char *login"
55.Ft struct passwd *
56.Fn getpwuid "uid_t uid"
57.Ft int
58.Fn setpassent "int  stayopen"
59.Ft void
60.Fn setpwent void
61.Ft void
62.Fn endpwent void
63.Sh DESCRIPTION
64These functions
65operate on the password database file
66which is described
67in
68.Xr passwd 5 .
69Each entry in the database is defined by the structure
70.Ar passwd
71found in the include
72file
73.Aq Pa pwd.h :
74.Bd -literal -offset indent
75struct passwd {
76	char	*pw_name;	/* user name */
77	char	*pw_passwd;	/* encrypted password */
78	uid_t	pw_uid;		/* user uid */
79	gid_t	pw_gid;		/* user gid */
80	time_t	pw_change;	/* password change time */
81	char	*pw_class;	/* user access class */
82	char	*pw_gecos;	/* Honeywell login info */
83	char	*pw_dir;	/* home directory */
84	char	*pw_shell;	/* default shell */
85	time_t	pw_expire;	/* account expiration */
86	int	pw_fields;	/* internal: fields filled in */
87};
88.Ed
89.Pp
90The functions
91.Fn getpwnam
92and
93.Fn getpwuid
94search the password database for the given login name or user uid,
95respectively, always returning the first one encountered.
96.Pp
97The
98.Fn getpwent
99function
100sequentially reads the password database and is intended for programs
101that wish to process the complete list of users.
102.Pp
103The
104.Fn setpassent
105function
106accomplishes two purposes.
107First, it causes
108.Fn getpwent
109to ``rewind'' to the beginning of the database.
110Additionally, if
111.Fa stayopen
112is non-zero, file descriptors are left open, significantly speeding
113up subsequent accesses for all of the routines.
114(This latter functionality is unnecessary for
115.Fn getpwent
116as it doesn't close its file descriptors by default.)
117.Pp
118It is dangerous for long-running programs to keep the file descriptors
119open as the database will become out of date if it is updated while the
120program is running.
121.Pp
122The
123.Fn setpwent
124function
125is identical to
126.Fn setpassent
127with an argument of zero.
128.Pp
129The
130.Fn endpwent
131function
132closes any open files.
133.Pp
134These routines have been written to ``shadow'' the password file, e.g.\&
135allow only certain programs to have access to the encrypted password.
136If the process which calls them has an effective uid of 0, the encrypted
137password will be returned, otherwise, the password field of the returned
138structure will point to the string
139.Ql * .
140.Sh YP/NIS INTERACTION
141When the
142.Xr yp 8
143password database is enabled, the
144.Fn getpwnam
145and
146.Fn getpwuid
147functions use the YP maps
148.Dq Li passwd.byname
149and
150.Dq Li passwd.byuid ,
151respectively, if the requested password entry is not found in the
152local database.  The
153.Fn getpwent
154function will step through the YP map
155.Dq Li passwd.byname
156if the entire map is enabled as described in
157.Xr passwd 5 .
158.Sh RETURN VALUES
159The functions
160.Fn getpwent ,
161.Fn getpwnam ,
162and
163.Fn getpwuid ,
164return a valid pointer to a passwd structure on success
165and a null pointer if end-of-file is reached or an error occurs.
166The
167.Fn setpassent
168function returns 0 on failure and 1 on success.
169The
170.Fn endpwent
171and
172.Fn setpwent
173functions
174have no return value.
175.Sh FILES
176.Bl -tag -width /etc/master.passwd -compact
177.It Pa /etc/pwd.db
178The insecure password database file
179.It Pa /etc/spwd.db
180The secure password database file
181.It Pa /etc/master.passwd
182The current password file
183.It Pa /etc/passwd
184A Version 7 format password file
185.El
186.Sh SEE ALSO
187.Xr getlogin 2 ,
188.Xr getgrent 3 ,
189.Xr passwd 5 ,
190.Xr pwd_mkdb 8 ,
191.Xr vipw 8 ,
192.Xr yp 8
193.Sh HISTORY
194The
195.Fn getpwent ,
196.Fn getpwnam ,
197.Fn getpwuid ,
198.Fn setpwent ,
199and
200.Fn endpwent
201functions appeared in
202.At v7 .
203The
204.Fn setpassent
205function appeared in
206.Bx 4.3 Reno .
207.Sh COMPATIBILITY
208The historic function
209.Xr setpwfile 3 ,
210which allowed the specification of alternate password databases,
211has been deprecated and is no longer available.
212.Sh BUGS
213The functions
214.Fn getpwent ,
215.Fn getpwnam ,
216and
217.Fn getpwuid ,
218leave their results in an internal static object and return
219a pointer to that object.
220Subsequent calls to
221the same function
222will modify the same object.
223