man3/getgrent.3

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