man3/getgrent.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\" Modified Sat Jul 24 19:29:54 1993 by Rik Faith (faith@cs.unc.edu)
  10 .TH GETGRENT 3 2021-03-22 "Linux man-pages (unreleased)"
  11 .SH NAME
  12 getgrent, setgrent, endgrent \- get group file entry
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <sys/types.h>
  19 .B #include <grp.h>
  20 .PP
  21 .B struct group *getgrent(void);
  22 .PP
  23 .B void setgrent(void);
  24 .B void endgrent(void);
  25 .fi
  26 .PP
  27 .RS -4
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .RE
  31 .PP
  32 .BR setgrent ():
  33 .nf
  34     _XOPEN_SOURCE >= 500
  35 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  36         || /* Glibc since 2.19: */ _DEFAULT_SOURCE
  37         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  38 .fi
  39 .PP
  40 .BR getgrent (),
  41 .BR endgrent ():
  42 .nf
  43     Since glibc 2.22:
  44         _XOPEN_SOURCE >= 500 || _DEFAULT_SOURCE
  45 .\"        || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  46     Glibc 2.21 and earlier
  47         _XOPEN_SOURCE >= 500
  48 .\"        || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  49             || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
  50             || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  51 .fi
  52 .SH DESCRIPTION
  53 The
  54 .BR getgrent ()
  55 function returns a pointer to a structure containing
  56 the broken-out fields of a record in the group database
  57 (e.g., the local group file
  58 .IR /etc/group ,
  59 NIS, and LDAP).
  60 The first time
  61 .BR getgrent ()
  62 is called,
  63 it returns the first entry; thereafter, it returns successive entries.
  64 .PP
  65 The
  66 .BR setgrent ()
  67 function rewinds to the beginning
  68 of the group database, to allow repeated scans.
  69 .PP
  70 The
  71 .BR endgrent ()
  72 function is used to close the group database
  73 after all processing has been performed.
  74 .PP
  75 The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows:
  76 .PP
  77 .in +4n
  78 .EX
  79 struct group {
  80     char   *gr_name;        /* group name */
  81     char   *gr_passwd;      /* group password */
  82     gid_t   gr_gid;         /* group ID */
  83     char  **gr_mem;         /* NULL\-terminated array of pointers
  84                                to names of group members */
  85 };
  86 .EE
  87 .in
  88 .PP
  89 For more information about the fields of this structure, see
  90 .BR group (5).
  91 .SH RETURN VALUE
  92 The
  93 .BR getgrent ()
  94 function returns a pointer to a
  95 .I group
  96 structure,
  97 or NULL if there are no more entries or an error occurs.
  98 .PP
  99 Upon error,
 100 .I errno
 101 may be set.
 102 If one wants to check
 103 .I errno
 104 after the call, it should be set to zero before the call.
 105 .PP
 106 The return value may point to a static area, and may be overwritten
 107 by subsequent calls to
 108 .BR getgrent (),
 109 .BR getgrgid (3),
 110 or
 111 .BR getgrnam (3).
 112 (Do not pass the returned pointer to
 113 .BR free (3).)
 114 .SH ERRORS
 115 .TP
 116 .B EAGAIN
 117 The service was temporarily unavailable; try again later.
 118 For NSS backends in glibc
 119 this indicates a temporary error talking to the backend.
 120 The error may correct itself, retrying later is suggested.
 121 .TP
 122 .B EINTR
 123 A signal was caught; see
 124 .BR signal (7).
 125 .TP
 126 .B EIO
 127 I/O error.
 128 .TP
 129 .B EMFILE
 130 The per-process limit on the number of open file descriptors has been reached.
 131 .TP
 132 .B ENFILE
 133 The system-wide limit on the total number of open files has been reached.
 134 .TP
 135 .\" not in POSIX
 136 .B ENOENT
 137 A necessary input file cannot be found.
 138 For NSS backends in glibc
 139 this indicates the backend is not correctly configured.
 140 .TP
 141 .B ENOMEM
 142 .\" not in POSIX
 143 Insufficient memory to allocate
 144 .I group
 145 structure.
 146 .TP
 147 .B ERANGE
 148 Insufficient buffer space supplied.
 149 .SH FILES
 150 .TP
 151 .I /etc/group
 152 local group database file
 153 .SH ATTRIBUTES
 154 For an explanation of the terms used in this section, see
 155 .BR attributes (7).
 156 .ad l
 157 .nh
 158 .TS
 159 allbox;
 160 lb lb lbx
 161 l l l.
 162 Interface       Attribute       Value
 163 T{
 164 .BR getgrent ()
 165 T}      Thread safety   T{
 166 MT-Unsafe race:grent
 167 race:grentbuf locale
 168 T}
 169 T{
 170 .BR setgrent (),
 171 .BR endgrent ()
 172 T}      Thread safety   T{
 173 MT-Unsafe race:grent locale
 174 T}
 175 .TE
 176 .hy
 177 .ad
 178 .sp 1
 179 .PP
 180 In the above table,
 181 .I grent
 182 in
 183 .I race:grent
 184 signifies that if any of the functions
 185 .BR setgrent (),
 186 .BR getgrent (),
 187 or
 188 .BR endgrent ()
 189 are used in parallel in different threads of a program,
 190 then data races could occur.
 191 .SH STANDARDS
 192 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
 193 .SH SEE ALSO
 194 .BR fgetgrent (3),
 195 .BR getgrent_r (3),
 196 .BR getgrgid (3),
 197 .BR getgrnam (3),
 198 .BR getgrouplist (3),
 199 .BR putgrent (3),
 200 .BR group (5)