1ENDGRENT(P)                POSIX Programmer's Manual               ENDGRENT(P)
2
3
4

NAME

6       endgrent, getgrent, setgrent - group database entry functions
7

SYNOPSIS

9       #include <grp.h>
10
11       void endgrent(void);
12       struct group *getgrent(void);
13       void setgrent(void);
14
15

DESCRIPTION

17       The  getgrent() function shall return a pointer to a structure contain‐
18       ing the broken-out fields of an entry in the group database. When first
19       called, getgrent() shall return a pointer to a group structure contain‐
20       ing the first entry in the group database. Thereafter, it shall  return
21       a  pointer  to a group structure containing the next group structure in
22       the group database, so successive calls  may  be  used  to  search  the
23       entire database.
24
25       An  implementation  that provides extended security controls may impose
26       further implementation-defined  restrictions  on  accessing  the  group
27       database.  In  particular, the system may deny the existence of some or
28       all of the group database entries associated  with  groups  other  than
29       those  groups  associated with the caller and may omit users other than
30       the caller from the list of members of groups in database entries  that
31       are returned.
32
33       The  setgrent()  function  shall  rewind  the  group  database to allow
34       repeated searches.
35
36       The endgrent() function may be called to close the group database  when
37       processing is complete.
38
39       These  functions need not be reentrant. A function that is not required
40       to be reentrant is not required to be thread-safe.
41

RETURN VALUE

43       When first called, getgrent() shall return a pointer to the first group
44       structure  in the group database. Upon subsequent calls it shall return
45       the next group structure in the group database.  The  getgrent()  func‐
46       tion  shall  return a null pointer on end-of-file or an error and errno
47       may be set to indicate the error.
48
49       The return value may point to a static area which is overwritten  by  a
50       subsequent call to getgrgid(), getgrnam(), or getgrent().
51

ERRORS

53       The getgrent() function may fail if:
54
55       EINTR  A signal was caught during the operation.
56
57       EIO    An I/O error has occurred.
58
59       EMFILE {OPEN_MAX}  file  descriptors  are currently open in the calling
60              process.
61
62       ENFILE The maximum allowable number of files is currently open  in  the
63              system.
64
65
66       The following sections are informative.
67

EXAMPLES

69       None.
70

APPLICATION USAGE

72       These  functions  are  provided due to their historical usage. Applica‐
73       tions should avoid  dependencies  on  fields  in  the  group  database,
74       whether the database is a single file, or where in the file system name
75       space the database resides. Applications should use getgrnam() and get‐
76       grgid() whenever possible because it avoids these dependencies.
77

RATIONALE

79       None.
80

FUTURE DIRECTIONS

82       None.
83

SEE ALSO

85       getgrgid()  ,  getgrnam()  , getlogin() , getpwent() , the Base Defini‐
86       tions volume of IEEE Std 1003.1-2001, <grp.h>
87

89       Portions of this text are reprinted and reproduced in  electronic  form
90       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
91       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
92       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
93       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
94       event of any discrepancy between this version and the original IEEE and
95       The Open Group Standard, the original IEEE and The Open Group  Standard
96       is  the  referee document. The original Standard can be obtained online
97       at http://www.opengroup.org/unix/online.html .
98
99
100
101IEEE/The Open Group                  2003                          ENDGRENT(P)
Impressum