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 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)getgrent.3    8.2 (Berkeley) 4/19/94
  33 .\" $FreeBSD: src/lib/libc/gen/getgrent.3,v 1.16 2001/10/01 16:08:51 ru Exp $
  34 .\"
  35 .Dd September 29, 1994
  36 .Dt GETGRENT 3
  37 .Os
  38 .Sh NAME
  39 .Nm endgrent ,
  40 .Nm getgrent ,
  41 .Nm getgrgid ,
  42 .Nm getgrgid_r ,
  43 .Nm getgrnam ,
  44 .Nm getgrnam_r ,
  45 .Nm setgrent ,
  46 .\" .Nm setgrfile ,
  47 .Nm setgroupent
  48 .Nd group database operations
  49 .Sh LIBRARY
  50 .Lb libc
  51 .Sh SYNOPSIS
  52 .In grp.h
  53 .Ft void
  54 .Fo endgrent
  55 .Fa void
  56 .Fc
  57 .Ft struct group *
  58 .Fo getgrent
  59 .Fa void
  60 .Fc
  61 .Ft struct group *
  62 .Fo getgrgid
  63 .Fa "gid_t gid"
  64 .Fc
  65 .Ft int
  66 .Fo getgrgid_r
  67 .Fa "gid_t gid"
  68 .Fa "struct group *grp"
  69 .Fa "char *buffer"
  70 .Fa "size_t bufsize"
  71 .Fa "struct group **result"
  72 .Fc
  73 .Ft struct group *
  74 .Fo getgrnam
  75 .Fa "const char *name"
  76 .Fc
  77 .Ft int
  78 .Fo getgrnam_r
  79 .Fa "const char *name"
  80 .Fa "struct group *grp"
  81 .Fa "char *buffer"
  82 .Fa "size_t bufsize"
  83 .Fa "struct group **result"
  84 .Fc
  85 .Ft void
  86 .Fo setgrent
  87 .Fa void
  88 .Fc
  89 .\" .Ft void
  90 .\" .Fn setgrfile "const char *name"
  91 .Ft int
  92 .Fo setgroupent
  93 .Fa "int stayopen"
  94 .Fc
  95 .Sh DESCRIPTION
  96 These functions operate on the group database file
  97 .Pa /etc/group ,
  98 which is described
  99 in
 100 .Xr group 5 .
 101 Each line of the database is defined by the structure
 102 .Ar group ,
 103 found in the include
 104 file
 105 .Aq Pa grp.h :
 106 .Bd -literal -offset indent
 107 struct group {
 108         char    *gr_name;       /* group name */
 109         char    *gr_passwd;     /* group password */
 110         int     gr_gid;         /* group id */
 111         char    **gr_mem;       /* group members */
 112 };
 113 .Ed
 114 .Pp
 115 The functions
 116 .Fn getgrnam
 117 and
 118 .Fn getgrgid
 119 search the group database for the given group name (pointed to by
 120 .Ar name )
 121 or the group id (pointed to by
 122 .Ar gid ) ,
 123 respectively, returning the first one encountered.  Identical group
 124 names or group ids may result in undefined behavior.
 125 .Pp
 126 All of these routines are thread-safe.
 127 The
 128 .Fn getgrent ,
 129 .Fn getgrgid ,
 130 and
 131 .Fn getgrnam
 132 routines return a pointer to a result managed by the system library in a
 133 thread-specific data structure.
 134 Every thread has space for a pointer to a struct group and allocates its own storage for the result.
 135 Neither previously returned values in memory nor a previously returned pointer value should be used
 136 by a thread after calling any one of these three routines.
 137 Memory allocated by a thread is automatically released on subsequent calls by the same thread to any of these
 138 three routines, and when the thread exits.
 139 .Pp
 140 The functions
 141 .Fn getgrgid_r
 142 and
 143 .Fn getgrnam_r
 144 take additional arguments which supply storage space for the returned result.
 145 The
 146 .Fa grp
 147 parameter is a pointer to a struct group, which must be allocated by the caller.
 148 The
 149 .Fa buffer
 150 parameter is a pointer to a block of memory with a size specified by
 151 .Pa bufsize .
 152 This buffer is used to hold the values which are pointed to by values filled in
 153 the
 154 .Fa grp
 155 structure.
 156 Zero is returned on success.
 157 If insufficient memory is supplied, these routines return ERANGE.
 158 .Pp
 159 The
 160 .Fn getgrent
 161 function
 162 sequentially reads the group database and is intended for programs
 163 that wish to step through the complete list of groups.
 164 .Pp
 165 All three routines will open the group file for reading, if necessary.
 166 .Pp
 167 The
 168 .Fn setgroupent
 169 function
 170 opens the file, or rewinds it if it is already open.  If
 171 .Fa stayopen
 172 is non-zero, file descriptors are left open, significantly speeding
 173 functions' subsequent calls.  This functionality is unnecessary for
 174 .Fn getgrent ,
 175 as it doesn't close its file descriptors by default.  It should also
 176 be noted that it is dangerous for long-running programs to use this
 177 functionality, as the group file may be updated.
 178 .Pp
 179 The
 180 .Fn setgrent
 181 function
 182 is identical to
 183 .Fn setgroupent
 184 with an argument of zero.
 185 .Pp
 186 The
 187 .Fn endgrent
 188 function
 189 closes any open files.
 190 .Sh RETURN VALUES
 191 The functions
 192 .Fn getgrent ,
 193 .Fn getgrgid ,
 194 and
 195 .Fn getgrnam
 196 each return a pointer to the group entry if successful; if end-of-file
 197 is reached or an error occurs, a null pointer is returned.
 198 The function
 199 .Fn setgroupent
 200 returns the value 1 if successful;
 201 otherwise, the value 0 is returned.
 202 The functions
 203 .Fn endgrent ,
 204 .Fn setgrent ,
 205 and
 206 .Fn setgrfile
 207 have no return value.
 208 .Sh FILES
 209 .Bl -tag -width /etc/group -compact
 210 .It Pa /etc/group
 211 group database file
 212 .El
 213 .Sh LEGACY SYNOPSIS
 214 .Fd #include <grp.h>
 215 .Pp
 216 .Ft int
 217 .br
 218 .Fo setgrent
 219 .Fa void
 220 .Fc ;
 221 .Pp
 222 The function
 223 .Fn setgrent
 224 returns the value 1 if successful;
 225 otherwise, the value 0 is returned.
 226 .Sh SEE ALSO
 227 .Xr getpwent 3 ,
 228 .Xr yp 8 ,
 229 .Xr group 5
 230 .Sh HISTORY
 231 The functions
 232 .Fn endgrent ,
 233 .Fn getgrent ,
 234 .Fn getgrnam ,
 235 .Fn getgrgid ,
 236 and
 237 .Fn setgrent
 238 appeared in
 239 .At v7 .
 240 The functions
 241 .Fn setgrfile
 242 and
 243 .Fn setgroupent
 244 appeared in
 245 .Bx 4.3 Reno .
 246 .Sh COMPATIBILITY
 247 The historic function
 248 .Fn setgrfile ,
 249 which allowed the specification of alternate password databases, has
 250 been deprecated and is no longer available.
 251 .Sh BUGS
 252 The functions
 253 .Fn getgrent ,
 254 .Fn getgrnam ,
 255 and
 256 .Fn getgrgid ,
 257 leave their results in internal thread-specific memory and return
 258 a pointer to that object.
 259 Subsequent calls to any of these three routines by the same thread will
 260 release the object and return a new pointer value.