mirror of https://github.com/mkerrisk/man-pages
132 lines
3.9 KiB
Plaintext
132 lines
3.9 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "ENDPWENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" endpwent
|
|
.SH NAME
|
|
endpwent, getpwent, setpwent \- user database functions
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <pwd.h>
|
|
.br
|
|
.sp
|
|
void endpwent(void);
|
|
.br
|
|
struct passwd *getpwent(void);
|
|
.br
|
|
void setpwent(void); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
These functions shall retrieve information about users.
|
|
.LP
|
|
The \fIgetpwent\fP() function shall return a pointer to a structure
|
|
containing the broken-out fields of an entry in the user
|
|
database. Each entry in the user database contains a \fBpasswd\fP
|
|
structure. When first called, \fIgetpwent\fP() shall return a
|
|
pointer to a \fBpasswd\fP structure containing the first entry in
|
|
the user database. Thereafter, it shall return a pointer to a
|
|
\fBpasswd\fP structure containing the next entry in the user database.
|
|
Successive calls can be used to search the entire user
|
|
database.
|
|
.LP
|
|
If an end-of-file or an error is encountered on reading, \fIgetpwent\fP()
|
|
shall return a null pointer.
|
|
.LP
|
|
An implementation that provides extended security controls may impose
|
|
further implementation-defined restrictions on accessing
|
|
the user database. In particular, the system may deny the existence
|
|
of some or all of the user database entries associated with
|
|
users other than the caller.
|
|
.LP
|
|
The \fIsetpwent\fP() function effectively rewinds the user database
|
|
to allow repeated searches.
|
|
.LP
|
|
The \fIendpwent\fP() function may be called to close the user database
|
|
when processing is complete.
|
|
.LP
|
|
These functions need not be reentrant. A function that is not required
|
|
to be reentrant is not required to be thread-safe.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
The \fIgetpwent\fP() function shall return a null pointer on end-of-file
|
|
or error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIgetpwent\fP(), \fIsetpwent\fP(), and \fIendpwent\fP() functions
|
|
may fail if:
|
|
.TP 7
|
|
.B EIO
|
|
An I/O error has occurred.
|
|
.sp
|
|
.LP
|
|
In addition, \fIgetpwent\fP() and \fIsetpwent\fP() may fail if:
|
|
.TP 7
|
|
.B EMFILE
|
|
{OPEN_MAX} file descriptors are currently open in the calling process.
|
|
.TP 7
|
|
.B ENFILE
|
|
The maximum allowable number of files is currently open in the system.
|
|
.sp
|
|
.LP
|
|
The return value may point to a static area which is overwritten by
|
|
a subsequent call to \fIgetpwuid\fP(), \fIgetpwnam\fP(), or
|
|
\fIgetpwent\fP().
|
|
.br
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Searching the User Database
|
|
.LP
|
|
The following example uses the \fIgetpwent\fP() function to get successive
|
|
entries in the user database, returning a pointer to
|
|
a \fBpasswd\fP structure that contains information about each user.
|
|
The call to \fIendpwent\fP() closes the user database and
|
|
cleans up.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <pwd.h>
|
|
\&...
|
|
struct passwd *p;
|
|
\&...
|
|
while ((p = getpwent ()) != NULL) {
|
|
\&...
|
|
}
|
|
.sp
|
|
|
|
endpwent();
|
|
\&...
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
These functions are provided due to their historical usage. Applications
|
|
should avoid dependencies on fields in the password
|
|
database, whether the database is a single file, or where in the file
|
|
system name space the database resides. Applications should
|
|
use \fIgetpwuid\fP() whenever possible because it avoids these dependencies.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIendgrent\fP() , \fIgetlogin\fP() , \fIgetpwnam\fP() , \fIgetpwuid\fP()
|
|
, the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<pwd.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|