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