getpwent.3

来自「<B>Digital的Unix操作系统VAX 4.2源码</B>」· 3 代码 · 共 151 行

.\" SCCSID: @(#)getpwent.3	8.2	12/3/90
.TH getpwent 3 
.SH Name
getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password entry
.SH Syntax
.nf
.B #include <pwd.h>
.PP
.B struct passwd *getpwent()
.PP
.B struct passwd *getpwuid(\fIuid\fP)
.B uid_t \fIuid\fP;
.PP
.B struct passwd *getpwnam(\fIname\fP)
.B char *\fIname\fP;
.PP
.B void setpwent()
.PP
.B void endpwent()
.PP
.B void setpwfile(\fIpathname\fP)
.B char *\fIpathname\fP
.fi
.SH Description
.NXR "getpwent subroutine"
.NXR "getpwuid subroutine"
.NXR "getpwnam subroutine"
.NXR "setpwent subroutine"
.NXR "endpwent subroutine"
.NXR "setpwfile subroutine"
.NXA "getpwent subroutine" "putpwent subroutine"
.NXR "password file (general)" "getting entry"
The routines,
.PN getpwent ,
.PN getpwuid
and
.PN getpwnam ,
each return a pointer to an object with the
following structure
containing the broken-out
fields of a line in the password database:
.EX
struct  passwd { /* see getpwent(3) */
        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;
};

struct passwd *getpwent(), *getpwuid(), *getpwnam();
.EE
.PP
The fields
.I pw_quota
and
.I pw_comment
are unused; the others have meanings described in
.MS passwd 5 .
.PP
A call to
.PN setpwent
has the effect of rewinding
the password file
to allow
repeated searches.
.PN Endpwent
may be called to
close the password database
when processing is complete.
.PP
The
.PN getpwent
subroutine simply retrieves the next
entry while
.PN getpwuid
and
.PN getpwnam
search until a matching
.I uid
or
.I name
is found
(or until all entries are exhausted).
The
.PN getpwent
subroutine keeps a pointer in the database, allowing
successive calls to be used 
to search the entire database.
.PP
A call to 
.PN setpwent
must be made before a 
.PN while
loop using 
.PN getpwent
in order to perform initialization and an
.PN endpwent
must be used after the loop.  Both
.PN getpwuid
and 
.PN getpwnam
make calls to 
.PN setpwent 
and 
.PN endpwent .
.PP
The
.PN setpwfile
subroutine sets the pathname of the ASCII passwd file and optional hashed database to
be used for local passwd lookups.
If a passwd file has been left open by a call to
.PN setpwent
or
.PN getpwent ,
.PN setpwfile
will close it first.
.PN Setpwfile
does not directly affect the use of distributed passwd databases.
.SH Restrictions
.NXR "getpwent subroutine" "restrictions"
All information is contained in a static area
so it must be copied if it is to be saved.
.PP
If YP is running, 
.PN getpwent
does not return the entries in any particular order.
See the
.I Guide to the Yellow Pages Service
for setup information.
.PP
The password database may also be distributed via the BIND/Hesiod
naming service.  See the
.I Guide to the BIND/Hesiod Service
for more information.
.SH Return Values
Null pointer
(0) returned on EOF or error.
.SH Files
.PN /etc/passwd
.SH See Also
getlogin(3), passwd(5), svc.conf(5)
.br
.I Guide to the BIND/Hesiod Service
.br
.I Guide to the Yellow Pages Service