Annotation of src/lib/libc/gen/getpwent.3, Revision 1.25.2.5
1.25.2.5! tron 1: .\" $NetBSD: getpwent.3,v 1.25.2.4 2005/07/11 21:23:04 tron 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.
1.23 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 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: .\"
1.7 cgd 30: .\" @(#)getpwent.3 8.2 (Berkeley) 12/11/93
1.1 cgd 31: .\"
1.25.2.4 tron 32: .Dd April 4, 2005
1.1 cgd 33: .Dt GETPWENT 3
34: .Os
35: .Sh NAME
36: .Nm getpwent ,
1.25.2.4 tron 37: .Nm getpwent_r ,
1.1 cgd 38: .Nm getpwnam ,
1.24 lukem 39: .Nm getpwnam_r ,
1.1 cgd 40: .Nm getpwuid ,
1.24 lukem 41: .Nm getpwuid_r ,
1.1 cgd 42: .Nm setpassent ,
43: .Nm setpwent ,
44: .Nm endpwent
45: .Nd password database operations
1.12 perry 46: .Sh LIBRARY
47: .Lb libc
1.1 cgd 48: .Sh SYNOPSIS
1.22 wiz 49: .In pwd.h
1.1 cgd 50: .Ft struct passwd *
51: .Fn getpwent void
1.25.2.4 tron 52: .Ft int
53: .Fo getpwent_r
54: .Fa "struct passwd *pw"
55: .Fa "char *buffer"
56: .Fa "size_t buflen"
57: .Fa "struct passwd **result"
58: .Fc
1.1 cgd 59: .Ft struct passwd *
1.24 lukem 60: .Fn getpwnam "const char *name"
1.25 wiz 61: .Ft int
1.24 lukem 62: .Fo getpwnam_r
63: .Fa "const char *name"
64: .Fa "struct passwd *pw"
65: .Fa "char *buffer"
66: .Fa "size_t buflen"
67: .Fa "struct passwd **result"
68: .Fc
1.1 cgd 69: .Ft struct passwd *
1.17 wiz 70: .Fn getpwuid "uid_t uid"
1.25 wiz 71: .Ft int
1.24 lukem 72: .Fo getpwuid_r
73: .Fa "uid_t uid"
74: .Fa "struct passwd *pw"
75: .Fa "char *buffer"
76: .Fa "size_t buflen"
77: .Fa "struct passwd **result"
78: .Fc
1.1 cgd 79: .Ft int
1.25 wiz 80: .Fn setpassent "int stayopen"
1.3 jtc 81: .Ft void
1.1 cgd 82: .Fn setpwent void
83: .Ft void
84: .Fn endpwent void
85: .Sh DESCRIPTION
86: These functions
1.24 lukem 87: operate on the password database
1.1 cgd 88: which is described
89: in
90: .Xr passwd 5 .
91: Each entry in the database is defined by the structure
92: .Ar passwd
93: found in the include
94: file
95: .Aq Pa pwd.h :
96: .Bd -literal -offset indent
97: struct passwd {
98: char *pw_name; /* user name */
99: char *pw_passwd; /* encrypted password */
100: uid_t pw_uid; /* user uid */
101: gid_t pw_gid; /* user gid */
102: time_t pw_change; /* password change time */
1.24 lukem 103: char *pw_class; /* user login class */
104: char *pw_gecos; /* general information */
1.1 cgd 105: char *pw_dir; /* home directory */
106: char *pw_shell; /* default shell */
107: time_t pw_expire; /* account expiration */
108: };
109: .Ed
110: .Pp
111: The functions
112: .Fn getpwnam
113: and
114: .Fn getpwuid
1.25.2.4 tron 115: search the password database for the given user name pointed to by
116: .Ar name
117: or user id pointed to by
118: .Ar uid
1.1 cgd 119: respectively, always returning the first one encountered.
1.24 lukem 120: Identical user names or user ids may result in undefined behavior.
121: .Pp
1.25.2.4 tron 122: The
123: .Fn getpwent
124: function
125: sequentially reads the password database and is intended for programs
126: that wish to process the complete list of users.
127: .Pp
1.24 lukem 128: The functions
1.25.2.4 tron 129: .Fn getpwnam_r ,
130: .Fn getpwuid_r ,
1.24 lukem 131: and
1.25.2.4 tron 132: .Fn getpwent_r
133: act like their non re-entrant counterparts, updating the contents of
1.24 lukem 134: .Ar pw
135: and storing a pointer to that in
136: .Ar result ,
137: and returning 0.
138: Storage used by
139: .Ar pw
140: is allocated from
141: .Ar buffer ,
142: which is
143: .Ar buflen
144: bytes in size.
145: If an error occurs,
146: an error number will be returned and
147: .Ar result
148: will point to null.
1.25.2.4 tron 149: Calling
150: .Fn getpwent_r
1.25.2.5! tron 151: from multiple threads will result in each thread reading a disjoint portion
1.25.2.4 tron 152: of the password database.
1.1 cgd 153: .Pp
154: The
155: .Fn setpassent
156: function
157: accomplishes two purposes.
158: First, it causes
159: .Fn getpwent
160: to ``rewind'' to the beginning of the database.
161: Additionally, if
162: .Fa stayopen
163: is non-zero, file descriptors are left open, significantly speeding
1.15 lukem 164: up subsequent accesses for all of the functions.
1.1 cgd 165: (This latter functionality is unnecessary for
166: .Fn getpwent
167: as it doesn't close its file descriptors by default.)
168: .Pp
169: It is dangerous for long-running programs to keep the file descriptors
1.7 cgd 170: open as the database will become out of date if it is updated while the
1.1 cgd 171: program is running.
172: .Pp
173: The
174: .Fn setpwent
175: function
1.4 jtc 176: is equivalent to
1.1 cgd 177: .Fn setpassent
178: with an argument of zero.
179: .Pp
180: The
181: .Fn endpwent
182: function
183: closes any open files.
184: .Pp
1.15 lukem 185: These functions have been written to ``shadow'' the password file, e.g.
1.1 cgd 186: allow only certain programs to have access to the encrypted password.
187: If the process which calls them has an effective uid of 0, the encrypted
1.5 jtc 188: password will be returned, otherwise, the password field of the returned
1.1 cgd 189: structure will point to the string
190: .Ql * .
191: .Sh RETURN VALUES
192: The functions
193: .Fn getpwent ,
194: .Fn getpwnam ,
195: and
196: .Fn getpwuid ,
197: return a valid pointer to a passwd structure on success
198: and a null pointer if end-of-file is reached or an error occurs.
1.4 jtc 199: The
1.1 cgd 200: .Fn setpassent
1.4 jtc 201: function returns 0 on failure and 1 on success.
1.1 cgd 202: The
203: .Fn endpwent
1.17 wiz 204: and
1.4 jtc 205: .Fn setpwent
206: functions
207: have no return value.
1.25.2.1 tron 208: The functions
209: .Fn getpwnam_r ,
1.25.2.4 tron 210: .Fn getpwuid_r ,
1.25.2.1 tron 211: and
1.25.2.4 tron 212: .Fn getpwent_r
1.25.2.1 tron 213: return
214: .Dv 0
215: on success and non-zero on failure.
1.1 cgd 216: .Sh FILES
217: .Bl -tag -width /etc/master.passwd -compact
1.6 jtc 218: .It Pa /etc/pwd.db
1.1 cgd 219: The insecure password database file
1.6 jtc 220: .It Pa /etc/spwd.db
1.1 cgd 221: The secure password database file
222: .It Pa /etc/master.passwd
223: The current password file
224: .It Pa /etc/passwd
225: A Version 7 format password file
226: .El
227: .Sh SEE ALSO
1.10 mikel 228: .Xr getlogin 2 ,
1.1 cgd 229: .Xr getgrent 3 ,
1.14 lukem 230: .Xr nsswitch.conf 5 ,
1.1 cgd 231: .Xr passwd 5 ,
1.16 ad 232: .Xr passwd.conf 5 ,
1.1 cgd 233: .Xr pwd_mkdb 8 ,
234: .Xr vipw 8
1.11 kleink 235: .Sh STANDARDS
236: The
1.25.2.2 tron 237: .Fn getpwnam
238: and
239: .Fn getpwuid ,
240: functions conform to
241: .St -p1003.1-90 .
242: The
243: .Fn getpwnam_r
244: and
245: .Fn getpwuid_r
246: functions conform to
247: .St -p1003.1c-95 .
248: The
1.24 lukem 249: .Fn endpwent ,
250: .Fn getpwent ,
1.11 kleink 251: and
1.24 lukem 252: .Fn setpwent
1.11 kleink 253: functions conform to
1.25.2.2 tron 254: .St -xpg4.2
255: and
256: .St -p1003.1-2004
257: (XSI extension).
1.1 cgd 258: .Sh HISTORY
259: The
260: .Nm getpwent ,
261: .Nm getpwnam ,
262: .Nm getpwuid ,
1.18 wiz 263: .Nm setpwent ,
1.1 cgd 264: and
265: .Nm endpwent
266: functions appeared in
267: .At v7 .
268: The
269: .Nm setpassent
270: function appeared in
271: .Bx 4.3 Reno .
1.24 lukem 272: The functions
273: .Fn getpwnam_r
274: and
275: .Fn getpwuid_r
276: appeared in
277: .Nx 3.0 .
1.1 cgd 278: .Sh BUGS
279: The functions
280: .Fn getpwent ,
281: .Fn getpwnam ,
282: and
283: .Fn getpwuid ,
284: leave their results in an internal static object and return
1.21 wiz 285: a pointer to that object.
286: Subsequent calls to any of these functions will modify the same object.
1.1 cgd 287: .Pp
1.15 lukem 288: The functions
1.1 cgd 289: .Fn getpwent ,
290: .Fn endpwent ,
291: .Fn setpassent ,
292: and
293: .Fn setpwent
294: are fairly useless in a networked environment and should be
295: avoided, if possible.
1.15 lukem 296: .Fn getpwent
297: makes no attempt to suppress duplicate information if multiple
298: sources are specified in
299: .Xr nsswitch.conf 5
1.1 cgd 300: .Sh COMPATIBILITY
301: The historic function
1.13 fair 302: .Fn setpwfile
1.9 mouse 303: which allowed the specification of alternative password databases,
1.1 cgd 304: 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