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 .\" 4. 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 .\"     From: @(#)getgrent.3    8.2 (Berkeley) 4/19/94
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd April 16, 2003
  32 .Dt GETGRENT 3
  33 .Os
  34 .Sh NAME
  35 .Nm getgrent ,
  36 .Nm getgrent_r ,
  37 .Nm getgrnam ,
  38 .Nm getgrnam_r ,
  39 .Nm getgrgid ,
  40 .Nm getgrgid_r ,
  41 .Nm setgroupent ,
  42 .Nm setgrent ,
  43 .Nm endgrent
  44 .Nd group database operations
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In grp.h
  49 .Ft struct group *
  50 .Fn getgrent void
  51 .Ft int
  52 .Fn getgrent_r "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
  53 .Ft struct group *
  54 .Fn getgrnam "const char *name"
  55 .Ft int
  56 .Fn getgrnam_r "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
  57 .Ft struct group *
  58 .Fn getgrgid "gid_t gid"
  59 .Ft int
  60 .Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
  61 .Ft int
  62 .Fn setgroupent "int stayopen"
  63 .Ft int
  64 .Fn setgrent void
  65 .Ft void
  66 .Fn endgrent void
  67 .Sh DESCRIPTION
  68 These functions operate on the group database file
  69 .Pa /etc/group
  70 which is described
  71 in
  72 .Xr group 5 .
  73 Each line of the database is defined by the structure
  74 .Vt group
  75 found in the include
  76 file
  77 .In grp.h :
  78 .Bd -literal -offset indent
  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;       /* group members */
  84 };
  85 .Ed
  86 .Pp
  87 The functions
  88 .Fn getgrnam
  89 and
  90 .Fn getgrgid
  91 search the group database for the given group name pointed to by
  92 .Fa name
  93 or the group id pointed to by
  94 .Fa gid ,
  95 respectively, returning the first one encountered.
  96 Identical group
  97 names or group gids may result in undefined behavior.
  98 .Pp
  99 The
 100 .Fn getgrent
 101 function
 102 sequentially reads the group database and is intended for programs
 103 that wish to step through the complete list of groups.
 104 .Pp
 105 The functions
 106 .Fn getgrent_r ,
 107 .Fn getgrnam_r ,
 108 and
 109 .Fn getgrgid_r
 110 are thread-safe versions of
 111 .Fn getgrent ,
 112 .Fn getgrnam ,
 113 and
 114 .Fn getgrgid ,
 115 respectively.
 116 The caller must provide storage for the results of the search in
 117 the
 118 .Fa grp ,
 119 .Fa buffer ,
 120 .Fa bufsize ,
 121 and
 122 .Fa result
 123 arguments.
 124 When these functions are successful, the
 125 .Fa grp
 126 argument will be filled-in, and a pointer to that argument will be
 127 stored in
 128 .Fa result .
 129 If an entry is not found or an error occurs,
 130 .Fa result
 131 will be set to
 132 .Dv NULL .
 133 .Pp
 134 These functions will open the group file for reading, if necessary.
 135 .Pp
 136 The
 137 .Fn setgroupent
 138 function
 139 opens the file, or rewinds it if it is already open.
 140 If
 141 .Fa stayopen
 142 is non-zero, file descriptors are left open, significantly speeding
 143 functions subsequent calls.
 144 This functionality is unnecessary for
 145 .Fn getgrent
 146 as it does not close its file descriptors by default.
 147 It should also
 148 be noted that it is dangerous for long-running programs to use this
 149 functionality as the group file may be updated.
 150 .Pp
 151 The
 152 .Fn setgrent
 153 function
 154 is identical to
 155 .Fn setgroupent
 156 with an argument of zero.
 157 .Pp
 158 The
 159 .Fn endgrent
 160 function
 161 closes any open files.
 162 .Sh RETURN VALUES
 163 The functions
 164 .Fn getgrent ,
 165 .Fn getgrnam ,
 166 and
 167 .Fn getgrgid ,
 168 return a pointer to a group structure on success or
 169 .Dv NULL
 170 if the entry is not found or if an error occurs.
 171 If an error does occur,
 172 .Va errno
 173 will be set.
 174 Note that programs must explicitly set
 175 .Va errno
 176 to zero before calling any of these functions if they need to
 177 distinguish between a non-existent entry and an error.
 178 The functions
 179 .Fn getgrent_r ,
 180 .Fn getgrnam_r ,
 181 and
 182 .Fn getgrgid_r
 183 return 0 if no error occurred, or an error number to indicate failure.
 184 It is not an error if a matching entry is not found.
 185 (Thus, if
 186 .Fa result
 187 is set to
 188 .Dv NULL
 189 and the return value is 0, no matching entry exists.)
 190 .Pp
 191 The functions
 192 .Fn setgroupent
 193 and
 194 .Fn setgrent
 195 return the value 1 if successful, otherwise the value
 196 0 is returned.
 197 The functions
 198 .Fn endgrent
 199 and
 200 .Fn setgrfile
 201 have no return value.
 202 .Sh FILES
 203 .Bl -tag -width /etc/group -compact
 204 .It Pa /etc/group
 205 group database file
 206 .El
 207 .Sh COMPATIBILITY
 208 The historic function
 209 .Fn setgrfile ,
 210 which allowed the specification of alternate password databases, has
 211 been deprecated and is no longer available.
 212 .Sh SEE ALSO
 213 .Xr getpwent 3 ,
 214 .Xr group 5 ,
 215 .Xr nsswitch.conf 5 ,
 216 .Xr yp 8
 217 .Sh STANDARDS
 218 The
 219 .Fn getgrent ,
 220 .Fn getgrnam ,
 221 .Fn getgrnam_r ,
 222 .Fn getgrgid ,
 223 .Fn getgrgid_r
 224 and
 225 .Fn endgrent
 226 functions conform to
 227 .St -p1003.1-96 .
 228 The
 229 .Fn setgrent
 230 function differs from that standard in that its return type is
 231 .Vt int
 232 rather than
 233 .Vt void .
 234 .Sh HISTORY
 235 The functions
 236 .Fn endgrent ,
 237 .Fn getgrent ,
 238 .Fn getgrnam ,
 239 .Fn getgrgid ,
 240 and
 241 .Fn setgrent
 242 appeared in
 243 .At v7 .
 244 The functions
 245 .Fn setgrfile
 246 and
 247 .Fn setgroupent
 248 appeared in
 249 .Bx 4.3 Reno .
 250 The functions
 251 .Fn getgrent_r ,
 252 .Fn getgrnam_r ,
 253 and
 254 .Fn getgrgid_r
 255 appeared in
 256 .Fx 5.1 .
 257 .Sh BUGS
 258 The functions
 259 .Fn getgrent ,
 260 .Fn getgrnam ,
 261 .Fn getgrgid ,
 262 .Fn setgroupent
 263 and
 264 .Fn setgrent
 265 leave their results in an internal static object and return
 266 a pointer to that object.
 267 Subsequent calls to
 268 the same function
 269 will modify the same object.
 270 .Pp
 271 The functions
 272 .Fn getgrent ,
 273 .Fn getgrent_r ,
 274 .Fn endgrent ,
 275 .Fn setgroupent ,
 276 and
 277 .Fn setgrent
 278 are fairly useless in a networked environment and should be
 279 avoided, if possible.
 280 The
 281 .Fn getgrent
 282 and
 283 .Fn getgrent_r
 284 functions
 285 make no attempt to suppress duplicate information if multiple
 286 sources are specified in
 287 .Xr nsswitch.conf 5 .