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