lib/libc/gen/getgrent.3

   1 .\"     $NetBSD: getgrent.3,v 1.31 2011/04/28 16:34:01 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 .In 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 FILES
 220 .Bl -tag -width /etc/group -compact
 221 .It Pa /etc/group
 222 group database file
 223 .El
 224 .Sh COMPATIBILITY
 225 The historic function
 226 .Fn setgrfile ,
 227 which allowed the specification of alternative group databases, has
 228 been deprecated and is no longer available.
 229 .Sh ERRORS
 230 The following error codes may be set in
 231 .Va errno
 232 for
 233 .Nm getgrent ,
 234 .Nm getgrent_r ,
 235 .Nm getgrnam ,
 236 .Nm getgrnam_r ,
 237 .Nm getgrgid ,
 238 .Nm getgrgid_r ,
 239 and
 240 .Nm setgroupent :
 241 .Bl -tag -width Er
 242 .It Bq Er EINTR
 243 A signal was caught during the database search.
 244 .It Bq Er EIO
 245 An I/O error has occurred.
 246 .It Bq Er EMFILE
 247 The limit on open files for this process has been reached.
 248 .It Bq Er ENFILE
 249 The system limit on open files has been reached.
 250 .El
 251 .Pp
 252 The following error code may be set in
 253 .Va errno
 254 for
 255 .Nm getgrent_r ,
 256 .Nm getgrnam_r ,
 257 and
 258 .Nm getgrgid_r :
 259 .Bl -tag -width Er
 260 .It Bq Er ERANGE
 261 The resulting
 262 .Ft struct group
 263 does not fit in the space defined by
 264 .Dv buffer
 265 and
 266 .Dv buflen
 267 .El
 268 .Pp
 269 Other
 270 .Dv errno
 271 values may be set depending on the specific database backends.
 272 .Sh SEE ALSO
 273 .Xr getpwent 3 ,
 274 .Xr group 5 ,
 275 .Xr nsswitch.conf 5
 276 .Sh STANDARDS
 277 The
 278 .Fn getgrgid
 279 and
 280 .Fn getgrnam
 281 functions conform to
 282 .St -p1003.1-90 .
 283 The
 284 .Fn getgrgid_r
 285 and
 286 .Fn getgrnam_r
 287 functions conform to
 288 .St -p1003.1c-95 .
 289 The
 290 .Fn endgrent ,
 291 .Fn getgrent ,
 292 and
 293 .Fn setgrent
 294 functions conform to
 295 .St -xpg4.2
 296 and
 297 .St -p1003.1-2004
 298 (XSI extension).
 299 .Sh HISTORY
 300 The functions
 301 .Fn endgrent ,
 302 .Fn getgrent ,
 303 .Fn getgrgid ,
 304 .Fn getgrnam ,
 305 and
 306 .Fn setgrent
 307 appeared in
 308 .At v7 .
 309 The functions
 310 .Fn setgrfile
 311 and
 312 .Fn setgroupent
 313 appeared in
 314 .Bx 4.3 Reno .
 315 The functions
 316 .Fn getgrgid_r
 317 and
 318 .Fn getgrnam_r
 319 appeared in
 320 .Nx 3.0 .
 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