1GETPWENT(3)                Library Functions Manual                GETPWENT(3)
2
3
4

NAME

6       getpwent, getpwnam, getpwuid, setpassent, setpwfile, setpwent, endpwent
7       - get password file entries
8

SYNOPSIS

10       #include <sys/types.h>
11       #include <pwd.h>
12
13       struct passwd *getpwent()
14
15       struct passwd *getpwnam(login)
16       char *login;
17
18       struct passwd *getpwuid(uid)
19       uid_t uid;
20
21       int setpassent(stayopen)
22       int stayopen;
23
24       void setpwfile(file)
25       char *file;
26
27       int setpwent()
28
29       void endpwent()
30

DESCRIPTION

32       Getpwent, getpwuid, and getpwnam each return a pointer to  a  structure
33       containing  the broken-out fields of a line in the password file.  This
34       structure is defined by the include file <pwd.h>, and contains the fol‐
35       lowing fields:
36
37              struct passwd {
38                   char *pw_name;           /* user name */
39                   char *pw_passwd;         /* encrypted password */
40                   uid_t     pw_uid;        /* user uid */
41                   gid_t     pw_gid;        /* user gid */
42                   time_t    pw_change;     /* password change time */
43                   char *pw_class;          /* user access class */
44                   char *pw_gecos;          /* Honeywell login info */
45                   char *pw_dir;            /* home directory */
46                   char *pw_shell;          /* default shell */
47                   time_t    pw_expire;     /* account expiration */
48              };
49
50       These fields are more completely described in passwd(5).
51
52       Getpwnam  and getpwuid search the password database for a matching user
53       name or user uid, respectively, returning the  first  one  encountered.
54       Identical user names or user uids may result in undefined behavior.
55
56       Getpwent  sequentially  reads the password database and is intended for
57       programs that wish to step through the complete list of users.
58
59       All three routines will open the password file for reading,  if  neces‐
60       sary.
61
62       Setpwfile  changes the default password file to file, thus allowing the
63       use of alternate password files.
64
65       Setpassent opens the file or rewinds it if  it  is  already  open.   If
66       stayopen  is  non-zero,  file  descriptors are left open, significantly
67       speeding up subsequent calls.  This functionality  is  unnecessary  for
68       getpwent  as  it  doesn't  close  its  file descriptors by default.  It
69       should also be noted that it is dangerous for long-running programs  to
70       use  this  functionality  as  the  password  file  may  be  updated  by
71       chpass(1), passwd(1), or vipw(8).
72
73       Setpwent is identical to setpassent with an argument of zero.
74
75       Endpwent closes any open files.
76
77       These routines have been written to ``shadow'' the password file,  e.g.
78       allow  only  certain programs to have access to the encrypted password.
79       This is done by using the mkpasswd(8) program,  which  creates  ndbm(3)
80       databases  that correspond to the password file, with the single excep‐
81       tion that, rather than storing the encrypted password in the  database,
82       it  stores the offset in the password file where the encrypted password
83       may be found.  Getpwent, getpwnam, and getpwuid will use the ndbm files
84       in preference to the ``real'' password files, only reading the password
85       file itself, to obtain the encrypted password, if the process  is  run‐
86       ning  with an effective user id equivalent to super-user.  If the pass‐
87       word file itself is protected, and the ndbm files are not,  this  makes
88       the  password available only to programs running with super-user privi‐
89       leges.
90

FILES

92       /etc/passwd
93

SEE ALSO

95       getlogin(3), getgrent(3), ndbm(3), passwd(5)
96

DIAGNOSTICS

98       The routines getpwent, getpwnam, and getpwuid, return a null pointer on
99       EOF  or  error.   Setpassent  and setpwent return 0 on failure and 1 on
100       success.  Endpwent and setpwfile have no return value.
101

BUGS

103       All information is contained in a static buffer which is overwritten by
104       each new call.  It must be copied elsewhere to be retained.
105
106       Intermixing  calls  to  getpwent with calls to getpwnam or getpwuid, or
107       intermixing calls to getpwnam and getpwuid, after using  setpassent  to
108       require  that  file  descriptors  be left open, may result in undefined
109       behavior.
110
111       The routines getpwent, endpwent, setpassent, and  setpwent  are  fairly
112       useless in a networked environment and should be avoided, if possible.
113
114
115
1167th Edition                    February 23, 1989                   GETPWENT(3)
Impressum