Commit | Line | Data |
---|---|---|
d1455a8c KB |
1 | .\" Copyright (c) 1988 The Regents of the University of California. |
2 | .\" All rights reserved. | |
62ab31a2 | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
d1455a8c | 5 | .\" |
babc0585 | 6 | .\" @(#)getpwent.3 6.7 (Berkeley) %G% |
4e6e003a | 7 | .\" |
3fb9eae6 | 8 | .TH GETPWENT 3 "" |
4e6e003a KM |
9 | .AT 3 |
10 | .SH NAME | |
babc0585 KB |
11 | getpwent, getpwnam, getpwuid, setpassent, setpwent, |
12 | endpwent \- get password file entries | |
4e6e003a KM |
13 | .SH SYNOPSIS |
14 | .nf | |
babc0585 KB |
15 | .ft B |
16 | #include <sys/types.h> | |
17 | #include <pwd.h> | |
18 | ||
19 | struct passwd *getpwent(void); | |
20 | struct passwd *getpwnam(char *login); | |
21 | struct passwd *getpwuid(uid_t uid); | |
22 | int setpassent(int stayopen); | |
23 | int setpwent(void); | |
24 | void endpwent(void); | |
25 | .ft R | |
4e6e003a KM |
26 | .fi |
27 | .SH DESCRIPTION | |
d1455a8c KB |
28 | .IR Getpwent , |
29 | .IR getpwuid , | |
4e6e003a KM |
30 | and |
31 | .I getpwnam | |
d1455a8c KB |
32 | each return a pointer to a structure containing the broken-out |
33 | fields of a line in the password file. This structure is defined | |
34 | by the include file | |
35 | .IR < pwd.h > , | |
36 | and contains the following fields: | |
4e6e003a | 37 | .PP |
d1455a8c | 38 | .RS |
4e6e003a | 39 | .nf |
62ab31a2 | 40 | struct passwd { |
d1455a8c KB |
41 | char *pw_name; /* user name */ |
42 | char *pw_passwd; /* encrypted password */ | |
43 | uid_t pw_uid; /* user uid */ | |
44 | gid_t pw_gid; /* user gid */ | |
45 | time_t pw_change; /* password change time */ | |
46 | char *pw_class; /* user access class */ | |
47 | char *pw_gecos; /* Honeywell login info */ | |
48 | char *pw_dir; /* home directory */ | |
49 | char *pw_shell; /* default shell */ | |
50 | time_t pw_expire; /* account expiration */ | |
62ab31a2 | 51 | }; |
4e6e003a KM |
52 | .fi |
53 | .RE | |
54 | .PP | |
d1455a8c | 55 | These fields are more completely described in |
4e6e003a KM |
56 | .IR passwd (5). |
57 | .PP | |
d1455a8c KB |
58 | .I Getpwnam |
59 | and | |
60 | .I getpwuid | |
61 | search the password database for a matching user name or user uid, | |
babc0585 | 62 | respectively, always returning the first one encountered. |
d1455a8c KB |
63 | .PP |
64 | .I Getpwent | |
65 | sequentially reads the password database and is intended for programs | |
babc0585 | 66 | that wish to process the complete list of users. |
d1455a8c KB |
67 | .PP |
68 | .I Setpassent | |
babc0585 KB |
69 | accomplishes two purposes. |
70 | First, it causes | |
71 | .I getpwent | |
72 | to ``rewind'' to the beginning of the database. | |
73 | Additionally, if | |
d1455a8c KB |
74 | .I stayopen |
75 | is non-zero, file descriptors are left open, significantly speeding | |
babc0585 KB |
76 | up subsequent accesses for all of the routines. |
77 | (This latter functionality is unnecessary for | |
d1455a8c | 78 | .I getpwent |
babc0585 KB |
79 | as it doesn't close its file descriptors by default.) |
80 | .PP | |
81 | It is dangerous for long-running programs to keep the file descriptors | |
82 | open the database will become out of date if it is updated while the | |
83 | program is running. | |
62ab31a2 | 84 | .PP |
1e00f4a7 | 85 | .I Setpwent |
d1455a8c KB |
86 | is identical to |
87 | .I setpassent | |
88 | with an argument of zero. | |
62ab31a2 KB |
89 | .PP |
90 | .I Endpwent | |
d1455a8c | 91 | closes any open files. |
62ab31a2 | 92 | .PP |
d1455a8c KB |
93 | These routines have been written to ``shadow'' the password file, e.g. |
94 | allow only certain programs to have access to the encrypted password. | |
babc0585 KB |
95 | If the process which calls them has an effective uid of 0, the encrypted |
96 | password will be returned, otherwise, the password field of the retuned | |
97 | structure will point to the string ``*''. | |
4e6e003a | 98 | .SH FILES |
babc0585 KB |
99 | /var/db/pwd.db The insecure password database file |
100 | .br | |
101 | /var/db/spwd.db The secure password database file | |
102 | .br | |
103 | /etc/master.passwd The current password file | |
104 | .br | |
105 | /etc/passwd A Version 7 format password file | |
4e6e003a | 106 | .SH "SEE ALSO" |
babc0585 | 107 | getlogin(3), getgrent(3), passwd(5), pwd_mkdb(8), vipw(8) |
4e6e003a | 108 | .SH DIAGNOSTICS |
c5892565 KM |
109 | The routines |
110 | .IR getpwent , | |
d1455a8c KB |
111 | .IR getpwnam , |
112 | and | |
c5892565 | 113 | .IR getpwuid , |
d1455a8c KB |
114 | return a null pointer on EOF or error. |
115 | .I Setpassent | |
c5892565 | 116 | and |
d1455a8c KB |
117 | .I setpwent |
118 | return 0 on failure and 1 on success. | |
62ab31a2 | 119 | .I Endpwent |
babc0585 | 120 | has no return value. |
4e6e003a | 121 | .SH BUGS |
d1455a8c | 122 | All information is contained in a static buffer which is overwritten |
babc0585 KB |
123 | by each new call. |
124 | It must be copied elsewhere to be retained. | |
d1455a8c KB |
125 | .PP |
126 | The routines | |
127 | .IR getpwent , | |
128 | .IR endpwent , | |
129 | .IR setpassent , | |
130 | and | |
131 | .IR setpwent | |
132 | are fairly useless in a networked environment and should be | |
133 | avoided, if possible. | |
babc0585 KB |
134 | .SH COMPATIBILITY |
135 | The historic function | |
136 | .IR setpwfile , | |
137 | which allowed the specification of alternate password databases, | |
138 | has been deprecated and is no longer available. |