diff options
Diffstat (limited to 'man3p/getpwent.3p')
-rw-r--r-- | man3p/getpwent.3p | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/man3p/getpwent.3p b/man3p/getpwent.3p new file mode 100644 index 000000000..cf3e4cb27 --- /dev/null +++ b/man3p/getpwent.3p @@ -0,0 +1,131 @@ +.\" 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 . |