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