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 void
  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
 193 .Fn setgroupent
 194 function returns the value 1 if successful, otherwise the value
 195 0 is returned.
 196 The
 197 .Fn endgrent
 198 function has no return value.
 199 .Sh FILES
 200 .Bl -tag -width /etc/group -compact
 201 .It Pa /etc/group
 202 group database file
 203 .El
 204 .Sh COMPATIBILITY
 205 The historic function
 206 .Fn setgrfile ,
 207 which allowed the specification of alternate password databases, has
 208 been deprecated and is no longer available.
 209 .Sh SEE ALSO
 210 .Xr getpwent 3 ,
 211 .Xr group 5 ,
 212 .Xr nsswitch.conf 5 ,
 213 .Xr yp 8
 214 .Sh STANDARDS
 215 The
 216 .Fn getgrent ,
 217 .Fn getgrnam ,
 218 .Fn getgrnam_r ,
 219 .Fn getgrgid ,
 220 .Fn getgrgid_r
 221 and
 222 .Fn endgrent
 223 functions conform to
 224 .St -p1003.1-96 .
 225 .Sh HISTORY
 226 The functions
 227 .Fn endgrent ,
 228 .Fn getgrent ,
 229 .Fn getgrnam ,
 230 .Fn getgrgid ,
 231 and
 232 .Fn setgrent
 233 appeared in
 234 .At v7 .
 235 The functions
 236 .Fn setgrfile
 237 and
 238 .Fn setgroupent
 239 appeared in
 240 .Bx 4.3 Reno .
 241 The functions
 242 .Fn getgrent_r ,
 243 .Fn getgrnam_r ,
 244 and
 245 .Fn getgrgid_r
 246 appeared in
 247 .Fx 5.1
 248 and
 249 .Dx 2.1 .
 250 .Sh BUGS
 251 The functions
 252 .Fn getgrent ,
 253 .Fn getgrnam ,
 254 .Fn getgrgid ,
 255 .Fn setgroupent
 256 and
 257 .Fn setgrent
 258 leave their results in an internal static object and return
 259 a pointer to that object.
 260 Subsequent calls to
 261 the same function
 262 will modify the same object.
 263 .Pp
 264 The functions
 265 .Fn getgrent ,
 266 .Fn getgrent_r ,
 267 .Fn endgrent ,
 268 .Fn setgroupent ,
 269 and
 270 .Fn setgrent
 271 are fairly useless in a networked environment and should be
 272 avoided, if possible.
 273 The
 274 .Fn getgrent
 275 and
 276 .Fn getgrent_r
 277 functions
 278 make no attempt to suppress duplicate information if multiple
 279 sources are specified in
 280 .Xr nsswitch.conf 5 .