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