![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to getpwent.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen|
Return to getpwent.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen |
1.1 root 1: .\" Copyright (c) 1988 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" Redistribution and use in source and binary forms are permitted provided
5: .\" that: (1) source distributions retain this entire copyright notice and
6: .\" comment, and (2) distributions including binaries display the following
7: .\" acknowledgement: ``This product includes software developed by the
8: .\" University of California, Berkeley and its contributors'' in the
9: .\" documentation or other materials provided with the distribution and in
10: .\" all advertising materials mentioning features or use of this software.
11: .\" Neither the name of the University nor the names of its contributors may
12: .\" be used to endorse or promote products derived from this software without
13: .\" specific prior written permission.
14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17: .\"
18: .\" @(#)getpwent.3 6.6 (Berkeley) 6/23/90
19: .\"
20: .TH GETPWENT 3 "June 23, 1990"
21: .AT 3
22: .SH NAME
23: getpwent, getpwnam, getpwuid, setpassent,
24: setpwfile, setpwent, endpwent \- get password file entries
25: .SH SYNOPSIS
26: .nf
27: .B #include <sys/types.h>
28: .B #include <pwd.h>
29: .PP
30: .B struct passwd *getpwent()
31: .PP
32: .B struct passwd *getpwnam(login)
33: .B char *login;
34: .PP
35: .B struct passwd *getpwuid(uid)
36: .B uid_t uid;
37: .PP
38: .B int setpassent(stayopen)
39: .B int stayopen;
40: .PP
41: .B void setpwfile(file)
42: .B char *file;
43: .PP
44: .B int setpwent()
45: .PP
46: .B void endpwent()
47: .fi
48: .SH DESCRIPTION
49: .IR Getpwent ,
50: .IR getpwuid ,
51: and
52: .I getpwnam
53: each return a pointer to a structure containing the broken-out
54: fields of a line in the password file. This structure is defined
55: by the include file
56: .IR < pwd.h > ,
57: and contains the following fields:
58: .PP
59: .RS
60: .nf
61: struct passwd {
62: char *pw_name; /* user name */
63: char *pw_passwd; /* encrypted password */
64: uid_t pw_uid; /* user uid */
65: gid_t pw_gid; /* user gid */
66: time_t pw_change; /* password change time */
67: char *pw_class; /* user access class */
68: char *pw_gecos; /* Honeywell login info */
69: char *pw_dir; /* home directory */
70: char *pw_shell; /* default shell */
71: time_t pw_expire; /* account expiration */
72: };
73: .fi
74: .RE
75: .PP
76: These fields are more completely described in
77: .IR passwd (5).
78: .PP
79: .I Getpwnam
80: and
81: .I getpwuid
82: search the password database for a matching user name or user uid,
83: respectively, returning the first one encountered. Identical
84: user names or user uids may result in undefined behavior.
85: .PP
86: .I Getpwent
87: sequentially reads the password database and is intended for programs
88: that wish to step through the complete list of users.
89: .PP
90: All three routines will open the password file for reading, if
91: necessary.
92: .PP
93: .I Setpwfile
94: changes the default password file to
95: .IR file ,
96: thus allowing the use of alternate password files.
97: .PP
98: .I Setpassent
99: opens the file or rewinds it if it is already open. If
100: .I stayopen
101: is non-zero, file descriptors are left open, significantly speeding
102: up subsequent calls. This functionality is unnecessary for
103: .I getpwent
104: as it doesn't close its file descriptors by default. It should also
105: be noted that it is dangerous for long-running programs to use this
106: functionality as the password file may be updated by
107: .IR chpass (1),
108: .IR passwd (1),
109: or
110: .IR vipw (8).
111: .PP
112: .I Setpwent
113: is identical to
114: .I setpassent
115: with an argument of zero.
116: .PP
117: .I Endpwent
118: closes any open files.
119: .PP
120: These routines have been written to ``shadow'' the password file, e.g.
121: allow only certain programs to have access to the encrypted password.
122: This is done by using the
123: .IR mkpasswd (8)
124: program, which creates
125: .IR ndbm (3)
126: databases that correspond to the password file, with the single exception
127: that, rather than storing the encrypted password in the database, it stores
128: the offset in the password file where the encrypted password may be found.
129: .IR Getpwent ,
130: .IR getpwnam ,
131: and
132: .I getpwuid
133: will use the
134: .I ndbm
135: files in preference to the ``real'' password files, only reading the
136: password file itself, to obtain the encrypted password, if the process
137: is running with an effective user id equivalent to super-user.
138: If the password file itself is protected, and the
139: .I ndbm
140: files are not, this makes the password available only to programs
141: running with super-user privileges.
142: .SH FILES
143: /etc/passwd
144: .SH "SEE ALSO"
145: getlogin(3), getgrent(3), ndbm(3), passwd(5)
146: .SH DIAGNOSTICS
147: The routines
148: .IR getpwent ,
149: .IR getpwnam ,
150: and
151: .IR getpwuid ,
152: return a null pointer on EOF or error.
153: .I Setpassent
154: and
155: .I setpwent
156: return 0 on failure and 1 on success.
157: .I Endpwent
158: and
159: .I setpwfile
160: have no return value.
161: .SH BUGS
162: All information is contained in a static buffer which is overwritten
163: by each new call. It must be copied elsewhere to be retained.
164: .PP
165: Intermixing calls to
166: .IR getpwent
167: with calls to
168: .I getpwnam
169: or
170: .IR getpwuid ,
171: or intermixing calls to
172: .I getpwnam
173: and
174: .IR getpwuid ,
175: after using
176: .I setpassent
177: to require that file descriptors be left open, may result
178: in undefined behavior.
179: .PP
180: The routines
181: .IR getpwent ,
182: .IR endpwent ,
183: .IR setpassent ,
184: and
185: .IR setpwent
186: are fairly useless in a networked environment and should be
187: avoided, if possible.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.