usr/src/lib/libc/gen/getpwent.3

.\" Copyright (c) 1988 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"     @(#)getpwent.3  6.4 (Berkeley) %G%
.\"
.TH GETPWENT 3  ""
.AT 3
.SH NAME
getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password file entry
.SH SYNOPSIS
.nf
.B #include <pwd.h>
.PP
.B struct passwd *getpwuid(uid)
.B uid_t uid;
.PP
.B struct passwd *getpwnam(name)
.B char *name;
.PP
.B struct passwd *getpwent()
.PP
.B void setpwent()
.PP
.B void endpwent()
.PP
.B setpwfile(name)
.B char *name;
.fi
.SH DESCRIPTION
.I Getpwent,
.I getpwuid
and
.I getpwnam
each return a pointer to an object with the following structure,
containing the broken-out fields of a line in the password file,
as described in
.IR < pwd.h > .
.RS
.PP
.nf
struct passwd {
        char    *pw_name;
        char    *pw_passwd;
        uid_t   pw_uid;
        gid_t   pw_gid;
        int     pw_quota;
        char    *pw_comment;
        char    *pw_gecos;
        char    *pw_dir;
        char    *pw_shell;
};
.ft R
.ad
.fi
.RE
.PP
The fields
.I pw_quota
and
.I pw_comment
are unused; the others have meanings described in
.IR passwd (5).
.PP
.I Setpwfile
changes the default password file to
.IR name ,
thus allowing usage of alternate password files.  If \fIndbm\fP databases
are available for any password files, they are used, otherwise the file
itself is linearly searched.
.PP
.I Setpwent
opens the database or file (closing any previously opened database or file)
or rewinds it if it is already open.
.PP
.I Endpwent
closes any open databases or files.
.PP
.I Getpwuid
and
.I getpwnam
search the entire database or file (opening it if necessary) for a matching
.I uid
or
.IR name .
.PP
For programs wishing to read the entire database,
.I getpwent
reads the next entry (opening the database or file if necessary).
.SH FILES
/etc/passwd
.SH "SEE ALSO"
getlogin(3), getgrent(3), passwd(5)
.SH DIAGNOSTICS
The routines
.IR getpwent ,
.IR getpwuid ,
and
.IR getpwnam ,
return a null pointer (0) on EOF or error.
.I Setpwent
returns 0 on failure, 1 on success.
.I Endpwent
and
.I setpwfile
have no return value.
.SH BUGS
All information is contained in a static area so it must be
copied if it is to be saved.