Annotation of src/lib/libc/gen/getpwent.3, Revision 1.25.2.8
1.25.2.8! tron 1: .\" $NetBSD: getpwent.3,v 1.25.2.7 2005/07/11 21:26:17 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.7 tron 32: .Dd April 19, 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 ,
1.25.2.7 tron 137: and returning
138: .Dv 0 .
1.24 lukem 139: Storage used by
140: .Ar pw
141: is allocated from
142: .Ar buffer ,
143: which is
144: .Ar buflen
145: bytes in size.
1.25.2.7 tron 146: If the requested entry cannot be found,
147: .Ar result
148: will point to
149: .Dv NULL
150: and
151: .Dv 0
152: will be returned.
1.24 lukem 153: If an error occurs,
1.25.2.7 tron 154: a non-zero error number will be returned and
1.24 lukem 155: .Ar result
1.25.2.7 tron 156: will point to
157: .Dv NULL .
1.25.2.4 tron 158: Calling
159: .Fn getpwent_r
1.25.2.5 tron 160: from multiple threads will result in each thread reading a disjoint portion
1.25.2.4 tron 161: of the password database.
1.1 cgd 162: .Pp
163: The
164: .Fn setpassent
165: function
166: accomplishes two purposes.
167: First, it causes
168: .Fn getpwent
1.25.2.6 tron 169: to
170: .Dq rewind
171: to the beginning of the database.
1.1 cgd 172: Additionally, if
173: .Fa stayopen
174: is non-zero, file descriptors are left open, significantly speeding
1.15 lukem 175: up subsequent accesses for all of the functions.
1.1 cgd 176: (This latter functionality is unnecessary for
177: .Fn getpwent
178: as it doesn't close its file descriptors by default.)
179: .Pp
180: It is dangerous for long-running programs to keep the file descriptors
1.7 cgd 181: open as the database will become out of date if it is updated while the
1.1 cgd 182: program is running.
183: .Pp
184: The
185: .Fn setpwent
186: function
1.4 jtc 187: is equivalent to
1.1 cgd 188: .Fn setpassent
189: with an argument of zero.
190: .Pp
191: The
192: .Fn endpwent
193: function
194: closes any open files.
195: .Pp
1.25.2.6 tron 196: These functions have been written to
197: .Dq shadow
198: the password file, e.g. allow only certain programs to have access
199: to the encrypted password.
1.1 cgd 200: If the process which calls them has an effective uid of 0, the encrypted
1.5 jtc 201: password will be returned, otherwise, the password field of the returned
1.1 cgd 202: structure will point to the string
203: .Ql * .
204: .Sh RETURN VALUES
205: The functions
206: .Fn getpwent ,
207: .Fn getpwnam ,
208: and
209: .Fn getpwuid ,
210: return a valid pointer to a passwd structure on success
1.25.2.7 tron 211: and a
1.25.2.8! tron 212: .Dv NULL
1.25.2.7 tron 213: pointer if the entry was not found or an error occurs.
1.4 jtc 214: The
1.1 cgd 215: .Fn setpassent
1.4 jtc 216: function returns 0 on failure and 1 on success.
1.1 cgd 217: The
218: .Fn endpwent
1.17 wiz 219: and
1.4 jtc 220: .Fn setpwent
221: functions
222: have no return value.
1.25.2.1 tron 223: The functions
224: .Fn getpwnam_r ,
1.25.2.4 tron 225: .Fn getpwuid_r ,
1.25.2.1 tron 226: and
1.25.2.4 tron 227: .Fn getpwent_r
1.25.2.1 tron 228: return
229: .Dv 0
1.25.2.7 tron 230: on success or entry not found and non-zero on failure.
1.1 cgd 231: .Sh FILES
232: .Bl -tag -width /etc/master.passwd -compact
1.6 jtc 233: .It Pa /etc/pwd.db
1.1 cgd 234: The insecure password database file
1.6 jtc 235: .It Pa /etc/spwd.db
1.1 cgd 236: The secure password database file
237: .It Pa /etc/master.passwd
238: The current password file
239: .It Pa /etc/passwd
240: A Version 7 format password file
241: .El
242: .Sh SEE ALSO
1.10 mikel 243: .Xr getlogin 2 ,
1.1 cgd 244: .Xr getgrent 3 ,
1.14 lukem 245: .Xr nsswitch.conf 5 ,
1.1 cgd 246: .Xr passwd 5 ,
1.16 ad 247: .Xr passwd.conf 5 ,
1.1 cgd 248: .Xr pwd_mkdb 8 ,
249: .Xr vipw 8
1.11 kleink 250: .Sh STANDARDS
251: The
1.25.2.2 tron 252: .Fn getpwnam
253: and
254: .Fn getpwuid ,
255: functions conform to
256: .St -p1003.1-90 .
257: The
258: .Fn getpwnam_r
259: and
260: .Fn getpwuid_r
261: functions conform to
262: .St -p1003.1c-95 .
263: The
1.24 lukem 264: .Fn endpwent ,
265: .Fn getpwent ,
1.11 kleink 266: and
1.24 lukem 267: .Fn setpwent
1.11 kleink 268: functions conform to
1.25.2.2 tron 269: .St -xpg4.2
270: and
271: .St -p1003.1-2004
272: (XSI extension).
1.1 cgd 273: .Sh HISTORY
274: The
275: .Nm getpwent ,
276: .Nm getpwnam ,
277: .Nm getpwuid ,
1.18 wiz 278: .Nm setpwent ,
1.1 cgd 279: and
280: .Nm endpwent
281: functions appeared in
282: .At v7 .
283: The
284: .Nm setpassent
285: function appeared in
286: .Bx 4.3 Reno .
1.24 lukem 287: The functions
288: .Fn getpwnam_r
289: and
290: .Fn getpwuid_r
291: appeared in
292: .Nx 3.0 .
1.1 cgd 293: .Sh BUGS
294: The functions
295: .Fn getpwent ,
296: .Fn getpwnam ,
297: and
298: .Fn getpwuid ,
299: leave their results in an internal static object and return
1.21 wiz 300: a pointer to that object.
301: Subsequent calls to any of these functions will modify the same object.
1.1 cgd 302: .Pp
1.15 lukem 303: The functions
1.1 cgd 304: .Fn getpwent ,
305: .Fn endpwent ,
306: .Fn setpassent ,
307: and
308: .Fn setpwent
309: are fairly useless in a networked environment and should be
310: avoided, if possible.
1.15 lukem 311: .Fn getpwent
312: makes no attempt to suppress duplicate information if multiple
313: sources are specified in
1.25.2.6 tron 314: .Xr nsswitch.conf 5 .
1.1 cgd 315: .Sh COMPATIBILITY
316: The historic function
1.13 fair 317: .Fn setpwfile
1.9 mouse 318: which allowed the specification of alternative password databases,
1.1 cgd 319: 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