lib/libc/gen/getgrent.3

   1 .\"     $NetBSD: getgrent.3,v 1.28 2005/05/25 10:05:22 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)getgrent.3  8.2 (Berkeley) 4/19/94
  31 .\"
  32 .Dd April 30, 2008
  33 .Dt GETGRENT 3
  34 .Os
  35 .Sh NAME
  36 .Nm getgrent ,
  37 .Nm getgrent_r ,
  38 .Nm getgrgid ,
  39 .Nm getgrgid_r ,
  40 .Nm getgrnam ,
  41 .Nm getgrnam_r ,
  42 .Nm setgroupent ,
  43 .\" .Nm setgrfile ,
  44 .Nm setgrent ,
  45 .Nm endgrent
  46 .Nd group database operations
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In grp.h
  51 .Ft struct group *
  52 .Fn getgrent void
  53 .Ft int
  54 .Fo getgrent_r
  55 .Fa "struct group *grp"
  56 .Fa "char *buffer"
  57 .Fa "size_t buflen"
  58 .Fa "struct group **result"
  59 .Fc
  60 .Ft struct group *
  61 .Fn getgrgid "gid_t gid"
  62 .Ft int
  63 .Fo getgrgid_r
  64 .Fa "gid_t gid"
  65 .Fa "struct group *grp"
  66 .Fa "char *buffer"
  67 .Fa "size_t buflen"
  68 .Fa "struct group **result"
  69 .Fc
  70 .Ft struct group *
  71 .Fn getgrnam "const char *name"
  72 .Ft int
  73 .Fo getgrnam_r
  74 .Fa "const char *name"
  75 .Fa "struct group *grp"
  76 .Fa "char *buffer"
  77 .Fa "size_t buflen"
  78 .Fa "struct group **result"
  79 .Fc
  80 .Ft int
  81 .Fn setgroupent "int stayopen"
  82 .\" .Ft void
  83 .\" .Fn setgrfile "const char *name"
  84 .Ft void
  85 .Fn setgrent void
  86 .Ft void
  87 .Fn endgrent void
  88 .Sh DESCRIPTION
  89 These functions operate on the group database which is described in
  90 .Xr group 5 .
  91 Each line of the database is defined by the structure
  92 .Ar group
  93 found in the include
  94 file
  95 .Aq Pa grp.h :
  96 .Bd -literal -offset indent
  97 struct group {
  98         char    *gr_name;       /* group name */
  99         char    *gr_passwd;     /* group password */
 100         gid_t   gr_gid;         /* group id */
 101         char    **gr_mem;       /* group members */
 102 };
 103 .Ed
 104 .Pp
 105 The functions
 106 .Fn getgrnam
 107 and
 108 .Fn getgrgid
 109 search the group database for the given group name pointed to by
 110 .Ar name
 111 or the group id pointed to by
 112 .Ar gid ,
 113 respectively, returning the first one encountered.
 114 Identical group names or group ids may result in undefined behavior.
 115 .Pp
 116 The
 117 .Fn getgrent
 118 function sequentially reads the group database and is intended for programs
 119 that wish to step through the complete list of groups.
 120 .Pp
 121 All three functions will open the group file for reading, if necessary.
 122 .Pp
 123 The functions
 124 .Fn getgrnam_r ,
 125 .Fn getgrgid_r ,
 126 and
 127 .Fn getgrent_r
 128 act like their non re-entrant counterparts
 129 respectively, updating the contents of
 130 .Ar grp
 131 and storing a pointer to that in
 132 .Ar result ,
 133 and returning
 134 .Dv 0 .
 135 Storage used by
 136 .Ar grp
 137 is allocated from
 138 .Ar buffer ,
 139 which is
 140 .Ar buflen
 141 bytes in size.
 142 If the requested entry cannot be found,
 143 .Ar result
 144 will point to
 145 .Dv NULL
 146 and
 147 .Dv 0
 148 will be returned.
 149 If an error occurs,
 150 a non-zero error number will be returned and
 151 .Ar result
 152 will point to
 153 .Dv NULL .
 154 Calling
 155 .Fn getgrent_r
 156 from multiple threads will result in each thread reading a disjoint portion
 157 of the group database.
 158 .Pp
 159 The
 160 .Fn setgroupent
 161 function opens the file, or rewinds it if it is already open.
 162 If
 163 .Fa stayopen
 164 is non-zero, file descriptors are left open, significantly speeding
 165 functions subsequent calls.
 166 This functionality is unnecessary for
 167 .Fn getgrent
 168 as it doesn't close its file descriptors by default.
 169 It should also be noted that it is dangerous for long-running
 170 programs to use this functionality as the group file may be updated.
 171 .Pp
 172 The
 173 .Fn setgrent
 174 function is equivalent to
 175 .Fn setgroupent
 176 with an argument of zero.
 177 .Pp
 178 The
 179 .Fn endgrent
 180 function closes any open files.
 181 .Sh RETURN VALUES
 182 The functions
 183 .Fn getgrgid ,
 184 .Fn getgrnam ,
 185 and
 186 .Fn getgrent
 187 return a valid pointer to a group structure on success
 188 and a
 189 .Dv NULL
 190 pointer if the entry was not found or an error occured.
 191 If an error occured, the global variable
 192 .Dv errno
 193 is set to indicate the nature of the failure.
 194 .Pp
 195 The functions
 196 .Fn getgrgid_r ,
 197 .Fn getgrnam_r ,
 198 and
 199 .Fn getgrent_r
 200 return
 201 .Dv 0
 202 on success or entry not found, and non-zero on failure, setting the global
 203 variable
 204 .Dv errno
 205 to indicate the nature of the failure.
 206 .Pp
 207 The
 208 .Fn setgroupent
 209 function returns the value 1 if successful, otherwise the value
 210 0 is returned, setting the global variable
 211 .Dv errno
 212 to indicate the nature of the failure.
 213 .Pp
 214 The
 215 .Fn endgrent
 216 and
 217 .Fn setgrent
 218 functions have no return value.
 219 .Sh ERRORS
 220 The following error codes may be set in
 221 .Va errno
 222 for
 223 .Nm getgrent ,
 224 .Nm getgrent_r ,
 225 .Nm getgrnam ,
 226 .Nm getgrnam_r ,
 227 .Nm getgrgid ,
 228 .Nm getgrgid_r ,
 229 and
 230 .Nm setgroupent :
 231 .Bl -tag -width Er
 232 .It Bq Er EIO
 233 An I/O error has occurred.
 234 .It Bq Er EINTR
 235 A signal was caught during the database search.
 236 .It Bq Er EMFILE
 237 The limit on open files for this process has been reached.
 238 .It Bq Er ENFILE
 239 The system limit on open files has been reached.
 240 .El
 241 .Pp
 242 The following error code may be set in
 243 .Va errno
 244 for
 245 .Nm getgrent_r ,
 246 .Nm getgrnam_r ,
 247 and
 248 .Nm getgrgid_r :
 249 .Bl -tag -width Er
 250 .It Bq Er ERANGE
 251 The resulting
 252 .Ft struct group
 253 does not fit in the space defined by
 254 .Dv buffer
 255 and
 256 .Dv buflen
 257 .El
 258 .Pp
 259 Other
 260 .Dv errno
 261 values may be set depending on the specific database backends.
 262 .Sh FILES
 263 .Bl -tag -width /etc/group -compact
 264 .It Pa /etc/group
 265 group database file
 266 .El
 267 .Sh SEE ALSO
 268 .Xr getpwent 3 ,
 269 .Xr group 5 ,
 270 .Xr nsswitch.conf 5
 271 .Sh STANDARDS
 272 The
 273 .Fn getgrgid
 274 and
 275 .Fn getgrnam
 276 functions conform to
 277 .St -p1003.1-90 .
 278 The
 279 .Fn getgrgid_r
 280 and
 281 .Fn getgrnam_r
 282 functions conform to
 283 .St -p1003.1c-95 .
 284 The
 285 .Fn endgrent ,
 286 .Fn getgrent ,
 287 and
 288 .Fn setgrent
 289 functions conform to
 290 .St -xpg4.2
 291 and
 292 .St -p1003.1-2004
 293 (XSI extension).
 294 .Sh HISTORY
 295 The functions
 296 .Fn endgrent ,
 297 .Fn getgrent ,
 298 .Fn getgrgid ,
 299 .Fn getgrnam ,
 300 and
 301 .Fn setgrent
 302 appeared in
 303 .At v7 .
 304 The functions
 305 .Fn setgrfile
 306 and
 307 .Fn setgroupent
 308 appeared in
 309 .Bx 4.3 Reno .
 310 The functions
 311 .Fn getgrgid_r
 312 and
 313 .Fn getgrnam_r
 314 appeared in
 315 .Nx 3.0 .
 316 .Sh COMPATIBILITY
 317 The historic function
 318 .Fn setgrfile ,
 319 which allowed the specification of alternative group databases, has
 320 been deprecated and is no longer available.
 321 .Sh BUGS
 322 The functions
 323 .Fn getgrent ,
 324 .Fn getgrgid ,
 325 .Fn getgrnam ,
 326 .Fn setgroupent
 327 and
 328 .Fn setgrent
 329 leave their results in an internal static object and return
 330 a pointer to that object.
 331 Subsequent calls to the same function will modify the same object.
 332 .Pp
 333 The functions
 334 .Fn getgrent ,
 335 .Fn endgrent ,
 336 .Fn setgroupent ,
 337 and
 338 .Fn setgrent
 339 are fairly useless in a networked environment and should be
 340 avoided, if possible.
 341 .Fn getgrent
 342 makes no attempt to suppress duplicate information if multiple
 343 sources are specified in
 344 .Xr nsswitch.conf 5