1ENDGRENT(3P) POSIX Programmer's Manual ENDGRENT(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 endgrent, getgrent, setgrent — group database entry functions
13
15 #include <grp.h>
16 void endgrent(void);
18 struct group *getgrent(void);
19 void setgrent(void);
20
22 The getgrent() function shall return a pointer to a structure contain‐
23 ing the broken-out fields of an entry in the group database. If the
24 group database is not already open, getgrent() shall open it and return
25 a pointer to a group structure containing the first entry in the data‐
26 base. Thereafter, it shall return a pointer to a group structure con‐
27 taining the next group structure in the group database, so successive
28 calls may be used to search the entire database.
29 An implementation that provides extended security controls may impose
31 further implementation-defined restrictions on accessing the group
32 database. In particular, the system may deny the existence of some or
33 all of the group database entries associated with groups other than
34 those groups associated with the caller and may omit users other than
35 the caller from the list of members of groups in database entries that
36 are returned.
37 The setgrent() function shall rewind the group database so that the
39 next getgrent() call returns the first entry, allowing repeated
40 searches.
41 The endgrent() function shall close the group database.
43 The setgrent() and endgrent() functions shall not change the setting of
45 errno if successful.
46 On error, the setgrent() and endgrent() functions shall set errno to
48 indicate the error.
49 Since no value is returned by the setgrent() and endgrent() functions,
51 an application wishing to check for error situations should set errno
52 to 0, then call the function, then check errno.
53 These functions need not be thread-safe.
55
57 On successful completion, getgrent() shall return a pointer to a group
58 structure. On end-of-file, getgrent() shall return a null pointer and
59 shall not change the setting of errno. On error, getgrent() shall
60 return a null pointer and errno shall be set to indicate the error.
61 The application shall not modify the structure to which the return
63 value points, nor any storage areas pointed to by pointers within the
64 structure. The returned pointer, and pointers within the structure,
65 might be invalidated or the structure or the storage areas might be
66 overwritten by a subsequent call to getgrgid(), getgrnam(), or get‐
67 grent(). The returned pointer, and pointers within the structure,
68 might also be invalidated if the calling thread is terminated.
69
71 These functions may fail if:
72 EINTR A signal was caught during the operation.
74 EIO An I/O error has occurred.
76 In addition, the getgrent() and setgrent() functions may fail if:
78 EMFILE All file descriptors available to the process are currently
80 open.
81 ENFILE The maximum allowable number of files is currently open in the
83 system.
84 The following sections are informative.
86
88 None.
89
91 These functions are provided due to their historical usage. Applica‐
92 tions should avoid dependencies on fields in the group database,
93 whether the database is a single file, or where in the file system name
94 space the database resides. Applications should use getgrnam() and get‐
95 grgid() whenever possible because it avoids these dependencies.
96
98 None.
99
101 None.
102
104 endpwent(), getgrgid(), getgrnam(), getlogin()
105 The Base Definitions volume of POSIX.1‐2017, <grp.h>
107
109 Portions of this text are reprinted and reproduced in electronic form
110 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
111 table Operating System Interface (POSIX), The Open Group Base Specifi‐
112 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
113 Electrical and Electronics Engineers, Inc and The Open Group. In the
114 event of any discrepancy between this version and the original IEEE and
115 The Open Group Standard, the original IEEE and The Open Group Standard
116 is the referee document. The original Standard can be obtained online
117 at http://www.opengroup.org/unix/online.html .
118 Any typographical or formatting errors that appear in this page are
120 most likely to have been introduced during the conversion of the source
121 files to man page format. To report such errors, see https://www.ker‐
122 nel.org/doc/man-pages/reporting_bugs.html .
123IEEE/The Open Group 2017 ENDGRENT(3P)