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 .\" @APPLE_LICENSE_HEADER_START@
  32 .\"
  33 .\" Portions Copyright (c) 2003-2013 Apple Inc.  All Rights Reserved.
  34 .\"
  35 .\" This file contains Original Code and/or Modifications of Original Code
  36 .\" as defined in and that are subject to the Apple Public Source License
  37 .\" Version 2.0 (the 'License'). You may not use this file except in
  38 .\" compliance with the License. Please obtain a copy of the License at
  39 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  40 .\" file.
  41 .\"
  42 .\" The Original Code and all software distributed under the License are
  43 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  44 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  45 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  46 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  47 .\" Please see the License for the specific language governing rights and
  48 .\" limitations under the License.
  49 .\"
  50 .\" @APPLE_LICENSE_HEADER_END@
  51 .\"
  52 .Dd October 26, 2011
  53 .Dt GETGRENT 3
  54 .Os
  55 .Sh NAME
  56 .Nm getgrent ,
  57 .\".Nm getgrent_r ,
  58 .Nm getgrnam ,
  59 .Nm getgrnam_r ,
  60 .Nm getgrgid ,
  61 .Nm getgrgid_r ,
  62 .Nm getgruuid ,
  63 .Nm getgruuid_r ,
  64 .Nm setgroupent ,
  65 .Nm setgrent ,
  66 .Nm endgrent
  67 .Nd group database operations
  68 .Sh LIBRARY
  69 Standard system libraries.
  70 .Sh SYNOPSIS
  71 .In grp.h
  72 .In uuid/uuid.h
  73 .Ft struct group *
  74 .Fn getgrent void
  75 .\".Ft int
  76 .\".Fn getgrent_r "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
  77 .Ft struct group *
  78 .Fn getgrnam "const char *name"
  79 .Ft int
  80 .Fn getgrnam_r "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
  81 .Ft struct group *
  82 .Fn getgrgid "gid_t gid"
  83 .Ft int
  84 .Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
  85 .Ft int
  86 .Fn getgruuid "uuid_t uuid"
  87 .Ft int
  88 .Fn getgruuid_r "uuid_t uuid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
  89 .Ft int
  90 .Fn setgroupent "int stayopen"
  91 .Ft void
  92 .Fn setgrent void
  93 .Ft void
  94 .Fn endgrent void
  95 .Sh DESCRIPTION
  96 .\"These functions operate on the group database file
  97 These functions obtain information from
  98 .Xr opendirectoryd 8 ,
  99 including records in
 100 .Pa /etc/group
 101 which is described
 102 in
 103 .Xr group 5 .
 104 Each line of the database is defined by the structure
 105 .Vt group
 106 found in the include
 107 file
 108 .In grp.h :
 109 .Bd -literal -offset indent
 110 struct group {
 111         char    *gr_name;       /* group name */
 112         char    *gr_passwd;     /* group password */
 113         gid_t   gr_gid;         /* group id */
 114         char    **gr_mem;       /* group members */
 115 };
 116 .Ed
 117 .Pp
 118 The functions
 119 .Fn getgrnam ,
 120 .Fn getgrgid ,
 121 and
 122 .Fn getgruuid
 123 search the group database for the given group name pointed to by
 124 .Fa name ,
 125 the group id given by
 126 .Fa gid ,
 127 or the UUID given by
 128 .Fa uuid
 129 respectively, returning the first one encountered.
 130 Identical group
 131 names, group gids, or uuids may result in undefined behavior.
 132 .Pp
 133 Note that the groups file
 134 .Pa /etc/group
 135 does not contain group UUIDs.
 136 The UUID for a group may be found using
 137 .Fn mbr_gid_to_uuid .
 138 .Pp
 139 On OS X, these routines are thread-safe and return a pointer to a
 140 thread-specific data structure.  The contents of this data
 141 structure are automatically released by subsequent calls to
 142 any of these routines on the same thread, or when the thread exits.
 143 These routines are therefore unsuitable for use in libraries or frameworks,
 144 from where they may overwrite the per-thread data that the calling
 145 application expects to find as a result of its own calls to these
 146 routines. Library and framework code should use the alternative reentrant
 147 variants detailed below.
 148 .Pp
 149 The
 150 .Fn getgrent
 151 function
 152 searches all available directory services on it's first invocation.
 153 It caches the returned entries in a list
 154 and returns group entries one at a time.
 155 .Pp
 156 .Em NOTE
 157 that
 158 .Fn getgrent
 159 may cause a very lengthy search for group records by
 160 .Nm opendirectoryd
 161 and may result in a large number of group records being cached
 162 by the calling process.
 163 Use of this function is not advised.
 164 .Pp
 165 The functions
 166 .Fn getgrnam_r ,
 167 .Fn getgrgid_r ,
 168 and
 169 .Fn getgruuid_r
 170 are alternative versions of
 171 .Fn getgrnam ,
 172 .Fn getgrgid ,
 173 and
 174 .Fn getgruuid
 175 respectively.
 176 The caller must provide storage for the results of the search in
 177 the
 178 .Fa grp ,
 179 .Fa buffer ,
 180 .Fa bufsize ,
 181 and
 182 .Fa result
 183 arguments.
 184 When these functions are successful, the
 185 .Fa grp
 186 argument will be filled-in, and a pointer to that argument will be
 187 stored in
 188 .Fa result .
 189 If an entry is not found or an error occurs,
 190 .Fa result
 191 will be set to
 192 .Dv NULL .
 193 .Pp
 194 These functions will open the group file for reading, if necessary.
 195 .Pp
 196 The
 197 .Fn setgroupent
 198 function causes
 199 .Fn getgrent
 200 to ``rewind'' to the beginning of the list of entries cached by a previous
 201 .Fn getgrent
 202 call.
 203 The cache is not cleared.
 204 The
 205 .Fa stayopen
 206 parameter value is unused on OS X.
 207 .Pp
 208 The
 209 .Fn setgrent
 210 and
 211 .Fn endgrent
 212 functions clear the cached results from a previous
 213 .Fn getgrent
 214 call.
 215 .Sh RETURN VALUES
 216 The functions
 217 .Fn getgrent ,
 218 .Fn getgrnam ,
 219 and
 220 .Fn getgrgid ,
 221 return a pointer to a group structure on success or
 222 .Dv NULL
 223 if the entry is not found or if an error occurs.
 224 If an error does occur,
 225 .Va errno
 226 will be set.
 227 Note that programs must explicitly set
 228 .Va errno
 229 to zero before calling any of these functions if they need to
 230 distinguish between a non-existent entry and an error.
 231 The functions
 232 .Fn getgrnam_r ,
 233 .Fn getgrgid_r ,
 234 and
 235 .Fn getgruuid_r
 236 return 0 if no error occurred, or an error number to indicate failure.
 237 It is not an error if a matching entry is not found.
 238 (Thus, if
 239 .Fa result
 240 is set to
 241 .Dv NULL
 242 and the return value is 0, no matching entry exists.)
 243 .Pp
 244 .Fn setgroupent
 245 returns the value 1 if successful, otherwise the value
 246 0 is returned.
 247 The functions
 248 .Fn setgrent ,
 249 .Fn endgrent ,
 250 and
 251 .Fn setgrfile
 252 have no return value.
 253 .Sh FILES
 254 .Bl -tag -width /etc/group -compact
 255 .It Pa /etc/group
 256 group database file
 257 .El
 258 .Sh COMPATIBILITY
 259 The historic function
 260 .Fn setgrfile ,
 261 which allowed the specification of alternate group databases, has
 262 been deprecated and is no longer available.
 263 .Sh SEE ALSO
 264 .Xr getpwent 3 ,
 265 .Xr group 5 ,
 266 .Xr mbr_gid_to_uuid 3,
 267 .Xr opendirectory 8 ,
 268 .Xr yp 8
 269 .Sh STANDARDS
 270 The
 271 .Fn getgrent ,
 272 .Fn getgrnam ,
 273 .Fn getgrnam_r ,
 274 .Fn getgrgid ,
 275 .Fn getgrgid_r
 276 and
 277 .Fn endgrent
 278 functions conform to
 279 .St -p1003.1-96 .
 280 The
 281 .Fn setgrent
 282 function differs from that standard in that its return type is
 283 .Vt int
 284 rather than
 285 .Vt void .
 286 .Sh HISTORY
 287 The functions
 288 .Fn endgrent ,
 289 .Fn getgrent ,
 290 .Fn getgrnam ,
 291 .Fn getgrgid ,
 292 and
 293 .Fn setgrent
 294 appeared in
 295 .At v7 .
 296 The functions
 297 .Fn setgrfile
 298 and
 299 .Fn setgroupent
 300 appeared in
 301 .Bx 4.3 Reno .
 302 The functions
 303 .\".Fn getgrent_r ,
 304 .\".Fn getgrnam_r ,
 305 .Fn getgrnam_r
 306 and
 307 .Fn getgrgid_r
 308 appeared in
 309 .Fx 5.1 .
 310 The functions
 311 .Fn getgruuid
 312 and
 313 .Fn getgruuid_r
 314 appeared in Mac OS X 10.8.
 315 .Sh BUGS
 316 The functions
 317 .Fn getgrent ,
 318 .Fn getgrnam ,
 319 .Fn getgrgid ,
 320 .Fn getgruuid ,
 321 .Fn setgroupent
 322 and
 323 .Fn setgrent
 324 leave their results in an internal thread-specific memory and return
 325 a pointer to that object.
 326 Subsequent calls to
 327 the same function
 328 will modify the same object.