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