update from Dave Borman; make "u=g" work.

[unix-history] / usr / src / lib / libc / gen / getpwent.3

.\" Copyright (c) 1988 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"	@(#)getpwent.3	6.6 (Berkeley) %G%
.\"
.TH GETPWENT 3  ""
.AT 3
.SH NAME
getpwent, getpwnam, getpwuid, setpassent,
setpwfile, setpwent, endpwent \- get password file entries
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
.B #include <pwd.h>
.PP
.B struct passwd *getpwent()
.PP
.B struct passwd *getpwnam(login)
.B char *login;
.PP
.B struct passwd *getpwuid(uid)
.B uid_t uid;
.PP
.B int setpassent(stayopen)
.B int stayopen;
.PP
.B void setpwfile(file)
.B char *file;
.PP
.B int setpwent()
.PP
.B void endpwent()
.fi
.SH DESCRIPTION
.IR Getpwent ,
.IR getpwuid ,
and
.I getpwnam
each return a pointer to a structure containing the broken-out
fields of a line in the password file.  This structure is defined
by the include file
.IR < pwd.h > ,
and contains the following fields:
.PP
.RS
.nf
struct passwd {
	char	*pw_name;			/* user name */
	char	*pw_passwd;		/* encrypted password */
	uid_t	pw_uid;		/* user uid */
	gid_t	pw_gid;		/* user gid */
	time_t	pw_change;	/* password change time */
	char	*pw_class;		/* user access class */
	char	*pw_gecos;		/* Honeywell login info */
	char	*pw_dir;			/* home directory */
	char	*pw_shell;		/* default shell */
	time_t	pw_expire;	/* account expiration */
};
.fi
.RE
.PP
These fields are more completely described in
.IR passwd (5).
.PP
.I Getpwnam
and
.I getpwuid
search the password database for a matching user name or user uid,
respectively, returning the first one encountered.  Identical
user names or user uids may result in undefined behavior.
.PP
.I Getpwent
sequentially reads the password database and is intended for programs
that wish to step through the complete list of users.
.PP
All three routines will open the password file for reading, if
necessary.
.PP
.I Setpwfile
changes the default password file to
.IR file ,
thus allowing the use of alternate password files.
.PP
.I Setpassent
opens the file or rewinds it if it is already open.  If
.I stayopen
is non-zero, file descriptors are left open, significantly speeding
up subsequent calls.  This functionality is unnecessary for
.I getpwent
as it doesn't close its file descriptors by default.  It should also
be noted that it is dangerous for long-running programs to use this
functionality as the password file may be updated by
.IR chpass (1),
.IR passwd (1),
or
.IR vipw (8).
.PP
.I Setpwent
is identical to
.I setpassent
with an argument of zero.
.PP
.I Endpwent
closes any open files.
.PP
These routines have been written to ``shadow'' the password file, e.g.
allow only certain programs to have access to the encrypted password.
This is done by using the
.IR mkpasswd (8)
program, which creates
.IR ndbm (3)
databases that correspond to the password file, with the single exception
that, rather than storing the encrypted password in the database, it stores
the offset in the password file where the encrypted password may be found.
.IR Getpwent ,
.IR getpwnam ,
and
.I getpwuid
will use the
.I ndbm
files in preference to the ``real'' password files, only reading the
password file itself, to obtain the encrypted password, if the process
is running with an effective user id equivalent to super-user.
If the password file itself is protected, and the
.I ndbm
files are not, this makes the password available only to programs
running with super-user privileges.
.SH FILES
/etc/passwd
.SH "SEE ALSO"
getlogin(3), getgrent(3), ndbm(3), passwd(5)
.SH DIAGNOSTICS
The routines
.IR getpwent ,
.IR getpwnam ,
and
.IR getpwuid ,
return a null pointer on EOF or error.
.I Setpassent
and
.I setpwent
return 0 on failure and 1 on success.
.I Endpwent
and
.I setpwfile
have no return value.
.SH BUGS
All information is contained in a static buffer which is overwritten
by each new call.  It must be copied elsewhere to be retained.
.PP
Intermixing calls to
.IR getpwent
with calls to
.I getpwnam
or
.IR getpwuid ,
or intermixing calls to
.I getpwnam
and
.IR getpwuid ,
after using
.I setpassent
to require that file descriptors be left open, may result
in undefined behavior.
.PP
The routines
.IR getpwent ,
.IR endpwent ,
.IR setpassent ,
and
.IR setpwent
are fairly useless in a networked environment and should be
avoided, if possible.