mirror of https://github.com/mkerrisk/man-pages
107 lines
3.6 KiB
Plaintext
107 lines
3.6 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "ENDGRENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" endgrent
|
|
.SH NAME
|
|
endgrent, getgrent, setgrent \- group database entry functions
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <grp.h>
|
|
.br
|
|
.sp
|
|
void endgrent(void);
|
|
.br
|
|
struct group *getgrent(void);
|
|
.br
|
|
void setgrent(void); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIgetgrent\fP() function shall return a pointer to a structure
|
|
containing the broken-out fields of an entry in the group
|
|
database. When first called, \fIgetgrent\fP() shall return a pointer
|
|
to a \fBgroup\fP structure containing the first entry in the
|
|
group database. Thereafter, it shall return a pointer to a \fBgroup\fP
|
|
structure containing the next group structure in the group
|
|
database, so successive calls may be used to search the entire database.
|
|
.LP
|
|
An implementation that provides extended security controls may impose
|
|
further implementation-defined restrictions on accessing
|
|
the group database. In particular, the system may deny the existence
|
|
of some or all of the group database entries associated with
|
|
groups other than those groups associated with the caller and may
|
|
omit users other than the caller from the list of members of
|
|
groups in database entries that are returned.
|
|
.LP
|
|
The \fIsetgrent\fP() function shall rewind the group database to allow
|
|
repeated searches.
|
|
.LP
|
|
The \fIendgrent\fP() function may be called to close the group 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
|
|
When first called, \fIgetgrent\fP() shall return a pointer to the
|
|
first group structure in the group database. Upon subsequent
|
|
calls it shall return the next group structure in the group database.
|
|
The \fIgetgrent\fP() function shall return a null pointer on
|
|
end-of-file or an error and \fIerrno\fP may be set to indicate the
|
|
error.
|
|
.LP
|
|
The return value may point to a static area which is overwritten by
|
|
a subsequent call to \fIgetgrgid\fP(), \fIgetgrnam\fP(), or
|
|
\fIgetgrent\fP().
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIgetgrent\fP() function may fail if:
|
|
.TP 7
|
|
.B EINTR
|
|
A signal was caught during the operation.
|
|
.TP 7
|
|
.B EIO
|
|
An I/O error has occurred.
|
|
.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
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
These functions are provided due to their historical usage. Applications
|
|
should avoid dependencies on fields in the group
|
|
database, whether the database is a single file, or where in the file
|
|
system name space the database resides. Applications should
|
|
use \fIgetgrnam\fP() and \fIgetgrgid\fP()
|
|
whenever possible because it avoids these dependencies.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIgetgrgid\fP() , \fIgetgrnam\fP() , \fIgetlogin\fP() , \fIgetpwent\fP()
|
|
, the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<grp.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 .
|