Annotation of src/lib/libc/gen/getpwent.3, Revision 1.22
1.22 ! wiz 1: .\" $NetBSD: getpwent.3,v 1.21 2002/10/01 16:48:34 wiz Exp $
1.7 cgd 2: .\"
3: .\" Copyright (c) 1988, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 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. All advertising materials mentioning features or use of this software
15: .\" must display the following acknowledgement:
16: .\" This product includes software developed by the University of
17: .\" California, Berkeley and its contributors.
18: .\" 4. Neither the name of the University nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
1.7 cgd 34: .\" @(#)getpwent.3 8.2 (Berkeley) 12/11/93
1.1 cgd 35: .\"
1.15 lukem 36: .Dd April 25, 1999
1.1 cgd 37: .Dt GETPWENT 3
38: .Os
39: .Sh NAME
40: .Nm getpwent ,
41: .Nm getpwnam ,
42: .Nm getpwuid ,
43: .Nm setpassent ,
44: .Nm setpwent ,
45: .Nm endpwent
46: .Nd password database operations
1.12 perry 47: .Sh LIBRARY
48: .Lb libc
1.1 cgd 49: .Sh SYNOPSIS
1.22 ! wiz 50: .In pwd.h
1.1 cgd 51: .Ft struct passwd *
52: .Fn getpwent void
53: .Ft struct passwd *
54: .Fn getpwnam "const char *login"
55: .Ft struct passwd *
1.17 wiz 56: .Fn getpwuid "uid_t uid"
1.1 cgd 57: .Ft int
58: .Fn setpassent "int stayopen"
1.3 jtc 59: .Ft void
1.1 cgd 60: .Fn setpwent void
61: .Ft void
62: .Fn endpwent void
63: .Sh DESCRIPTION
64: These functions
65: operate on the password database file
66: which is described
67: in
68: .Xr passwd 5 .
69: Each entry in the database is defined by the structure
70: .Ar passwd
71: found in the include
72: file
73: .Aq Pa pwd.h :
74: .Bd -literal -offset indent
75: struct 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: };
87: .Ed
88: .Pp
89: The functions
90: .Fn getpwnam
91: and
92: .Fn getpwuid
93: search the password database for the given login name or user uid,
94: respectively, always returning the first one encountered.
95: .Pp
96: The
97: .Fn getpwent
98: function
99: sequentially reads the password database and is intended for programs
100: that wish to process the complete list of users.
101: .Pp
102: The
103: .Fn setpassent
104: function
105: accomplishes two purposes.
106: First, it causes
107: .Fn getpwent
108: to ``rewind'' to the beginning of the database.
109: Additionally, if
110: .Fa stayopen
111: is non-zero, file descriptors are left open, significantly speeding
1.15 lukem 112: up subsequent accesses for all of the functions.
1.1 cgd 113: (This latter functionality is unnecessary for
114: .Fn getpwent
115: as it doesn't close its file descriptors by default.)
116: .Pp
117: It is dangerous for long-running programs to keep the file descriptors
1.7 cgd 118: open as the database will become out of date if it is updated while the
1.1 cgd 119: program is running.
120: .Pp
121: The
122: .Fn setpwent
123: function
1.4 jtc 124: is equivalent to
1.1 cgd 125: .Fn setpassent
126: with an argument of zero.
127: .Pp
128: The
129: .Fn endpwent
130: function
131: closes any open files.
132: .Pp
1.15 lukem 133: These functions have been written to ``shadow'' the password file, e.g.
1.1 cgd 134: allow only certain programs to have access to the encrypted password.
135: If the process which calls them has an effective uid of 0, the encrypted
1.5 jtc 136: password will be returned, otherwise, the password field of the returned
1.1 cgd 137: structure will point to the string
138: .Ql * .
139: .Sh RETURN VALUES
140: The functions
141: .Fn getpwent ,
142: .Fn getpwnam ,
143: and
144: .Fn getpwuid ,
145: return a valid pointer to a passwd structure on success
146: and a null pointer if end-of-file is reached or an error occurs.
1.4 jtc 147: The
1.1 cgd 148: .Fn setpassent
1.4 jtc 149: function returns 0 on failure and 1 on success.
1.1 cgd 150: The
151: .Fn endpwent
1.17 wiz 152: and
1.4 jtc 153: .Fn setpwent
154: functions
155: have no return value.
1.1 cgd 156: .Sh FILES
157: .Bl -tag -width /etc/master.passwd -compact
1.6 jtc 158: .It Pa /etc/pwd.db
1.1 cgd 159: The insecure password database file
1.6 jtc 160: .It Pa /etc/spwd.db
1.1 cgd 161: The secure password database file
162: .It Pa /etc/master.passwd
163: The current password file
164: .It Pa /etc/passwd
165: A Version 7 format password file
166: .El
167: .Sh SEE ALSO
1.10 mikel 168: .Xr getlogin 2 ,
1.1 cgd 169: .Xr getgrent 3 ,
1.14 lukem 170: .Xr nsswitch.conf 5 ,
1.1 cgd 171: .Xr passwd 5 ,
1.16 ad 172: .Xr passwd.conf 5 ,
1.1 cgd 173: .Xr pwd_mkdb 8 ,
174: .Xr vipw 8
1.11 kleink 175: .Sh STANDARDS
176: The
177: .Fn getpwnam
178: and
179: .Fn getpwuid
180: functions conform to
181: .St -p1003.1-90 .
1.1 cgd 182: .Sh HISTORY
183: The
184: .Nm getpwent ,
185: .Nm getpwnam ,
186: .Nm getpwuid ,
1.18 wiz 187: .Nm setpwent ,
1.1 cgd 188: and
189: .Nm endpwent
190: functions appeared in
191: .At v7 .
192: The
193: .Nm setpassent
194: function appeared in
195: .Bx 4.3 Reno .
196: .Sh BUGS
197: The functions
198: .Fn getpwent ,
199: .Fn getpwnam ,
200: and
201: .Fn getpwuid ,
202: leave their results in an internal static object and return
1.21 wiz 203: a pointer to that object.
204: Subsequent calls to any of these functions will modify the same object.
1.1 cgd 205: .Pp
1.15 lukem 206: The functions
1.1 cgd 207: .Fn getpwent ,
208: .Fn endpwent ,
209: .Fn setpassent ,
210: and
211: .Fn setpwent
212: are fairly useless in a networked environment and should be
213: avoided, if possible.
1.15 lukem 214: .Fn getpwent
215: makes no attempt to suppress duplicate information if multiple
216: sources are specified in
217: .Xr nsswitch.conf 5
1.1 cgd 218: .Sh COMPATIBILITY
219: The historic function
1.13 fair 220: .Fn setpwfile
1.9 mouse 221: which allowed the specification of alternative password databases,
1.1 cgd 222: has been deprecated and is no longer available.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to getpwent.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / gen