lib/libc/gen/getgrent.3

   1 .\" Copyright (c) 1989, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd July 31, 2016
  29 .Dt GETGRENT 3
  30 .Os
  31 .Sh NAME
  32 .Nm getgrent ,
  33 .Nm getgrent_r ,
  34 .Nm getgrnam ,
  35 .Nm getgrnam_r ,
  36 .Nm getgrgid ,
  37 .Nm getgrgid_r ,
  38 .Nm setgroupent ,
  39 .Nm setgrent ,
  40 .Nm endgrent
  41 .Nd group database operations
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In grp.h
  46 .Ft struct group *
  47 .Fn getgrent void
  48 .Ft int
  49 .Fn getgrent_r "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
  50 .Ft struct group *
  51 .Fn getgrnam "const char *name"
  52 .Ft int
  53 .Fn getgrnam_r "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
  54 .Ft struct group *
  55 .Fn getgrgid "gid_t gid"
  56 .Ft int
  57 .Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
  58 .Ft int
  59 .Fn setgroupent "int stayopen"
  60 .Ft void
  61 .Fn setgrent void
  62 .Ft void
  63 .Fn endgrent void
  64 .Sh DESCRIPTION
  65 These functions operate on the group database file
  66 .Pa /etc/group
  67 which is described
  68 in
  69 .Xr group 5 .
  70 Each line of the database is defined by the structure
  71 .Vt group
  72 found in the include
  73 file
  74 .In grp.h :
  75 .Bd -literal -offset indent
  76 struct group {
  77         char    *gr_name;       /* group name */
  78         char    *gr_passwd;     /* group password */
  79         gid_t   gr_gid;         /* group id */
  80         char    **gr_mem;       /* group members */
  81 };
  82 .Ed
  83 .Pp
  84 The functions
  85 .Fn getgrnam
  86 and
  87 .Fn getgrgid
  88 search the group database for the given group name pointed to by
  89 .Fa name
  90 or the group id pointed to by
  91 .Fa gid ,
  92 respectively, returning the first one encountered.
  93 Identical group
  94 names or group gids may result in undefined behavior.
  95 .Pp
  96 The
  97 .Fn getgrent
  98 function
  99 sequentially reads the group database and is intended for programs
 100 that wish to step through the complete list of groups.
 101 .Pp
 102 The functions
 103 .Fn getgrent_r ,
 104 .Fn getgrnam_r ,
 105 and
 106 .Fn getgrgid_r
 107 are thread-safe versions of
 108 .Fn getgrent ,
 109 .Fn getgrnam ,
 110 and
 111 .Fn getgrgid ,
 112 respectively.
 113 The caller must provide storage for the results of the search in
 114 the
 115 .Fa grp ,
 116 .Fa buffer ,
 117 .Fa bufsize ,
 118 and
 119 .Fa result
 120 arguments.
 121 When these functions are successful, the
 122 .Fa grp
 123 argument will be filled-in, and a pointer to that argument will be
 124 stored in
 125 .Fa result .
 126 If an entry is not found or an error occurs,
 127 .Fa result
 128 will be set to
 129 .Dv NULL .
 130 .Pp
 131 These functions will open the group file for reading, if necessary.
 132 .Pp
 133 The
 134 .Fn setgroupent
 135 function
 136 opens the file, or rewinds it if it is already open.
 137 If
 138 .Fa stayopen
 139 is non-zero, file descriptors are left open, significantly speeding
 140 functions subsequent calls.
 141 This functionality is unnecessary for
 142 .Fn getgrent
 143 as it does not close its file descriptors by default.
 144 It should also
 145 be noted that it is dangerous for long-running programs to use this
 146 functionality as the group file may be updated.
 147 .Pp
 148 The
 149 .Fn setgrent
 150 function
 151 is identical to
 152 .Fn setgroupent
 153 with an argument of zero.
 154 .Pp
 155 The
 156 .Fn endgrent
 157 function
 158 closes any open files.
 159 .Sh RETURN VALUES
 160 The functions
 161 .Fn getgrent ,
 162 .Fn getgrnam ,
 163 and
 164 .Fn getgrgid ,
 165 return a pointer to a group structure on success or
 166 .Dv NULL
 167 if the entry is not found or if an error occurs.
 168 If an error does occur,
 169 .Va errno
 170 will be set.
 171 Note that programs must explicitly set
 172 .Va errno
 173 to zero before calling any of these functions if they need to
 174 distinguish between a non-existent entry and an error.
 175 The functions
 176 .Fn getgrent_r ,
 177 .Fn getgrnam_r ,
 178 and
 179 .Fn getgrgid_r
 180 return 0 if no error occurred, or an error number to indicate failure.
 181 It is not an error if a matching entry is not found.
 182 (Thus, if
 183 .Fa result
 184 is set to
 185 .Dv NULL
 186 and the return value is 0, no matching entry exists.)
 187 .Pp
 188 The function
 189 .Fn setgroupent
 190 returns the value 1 if successful, otherwise the value
 191 0 is returned.
 192 The functions
 193 .Fn endgrent ,
 194 .Fn setgrent
 195 and
 196 .Fn setgrfile
 197 have no return value.
 198 .Sh FILES
 199 .Bl -tag -width /etc/group -compact
 200 .It Pa /etc/group
 201 group database file
 202 .El
 203 .Sh COMPATIBILITY
 204 The historic function
 205 .Fn setgrfile ,
 206 which allowed the specification of alternate password databases, has
 207 been deprecated and is no longer available.
 208 .Sh SEE ALSO
 209 .Xr getpwent 3 ,
 210 .Xr group 5 ,
 211 .Xr nsswitch.conf 5 ,
 212 .Xr yp 8
 213 .Sh STANDARDS
 214 The
 215 .Fn getgrent ,
 216 .Fn getgrnam ,
 217 .Fn getgrnam_r ,
 218 .Fn getgrgid ,
 219 .Fn getgrgid_r
 220 and
 221 .Fn endgrent
 222 functions conform to
 223 .St -p1003.1-96 .
 224 The
 225 .Fn setgrent
 226 function differs from that standard in that its return type is
 227 .Vt int
 228 rather than
 229 .Vt void .
 230 .Sh HISTORY
 231 The functions
 232 .Fn endgrent ,
 233 .Fn getgrent ,
 234 .Fn getgrnam ,
 235 .Fn getgrgid ,
 236 and
 237 .Fn setgrent
 238 appeared in
 239 .At v7 .
 240 The functions
 241 .Fn setgrfile
 242 and
 243 .Fn setgroupent
 244 appeared in
 245 .Bx 4.3 Reno .
 246 The functions
 247 .Fn getgrent_r ,
 248 .Fn getgrnam_r ,
 249 and
 250 .Fn getgrgid_r
 251 appeared in
 252 .Fx 5.1 .
 253 .Sh BUGS
 254 The functions
 255 .Fn getgrent ,
 256 .Fn getgrnam ,
 257 .Fn getgrgid ,
 258 .Fn setgroupent
 259 and
 260 .Fn setgrent
 261 leave their results in an internal static object and return
 262 a pointer to that object.
 263 Subsequent calls to
 264 the same function
 265 will modify the same object.
 266 .Pp
 267 The functions
 268 .Fn getgrent ,
 269 .Fn getgrent_r ,
 270 .Fn endgrent ,
 271 .Fn setgroupent ,
 272 and
 273 .Fn setgrent
 274 are fairly useless in a networked environment and should be
 275 avoided, if possible.
 276 The
 277 .Fn getgrent
 278 and
 279 .Fn getgrent_r
 280 functions
 281 make no attempt to suppress duplicate information if multiple
 282 sources are specified in
 283 .Xr nsswitch.conf 5 .