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