lib/libc/gen/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.12.2.4 2003/03/15 15:11:05 trhodes Exp $
  34 .\" $DragonFly: src/lib/libc/gen/getgrent.3,v 1.3 2006/02/17 19:35:06 swildner Exp $
  35 .\"
  36 .Dd September 29, 1994
  37 .Dt GETGRENT 3
  38 .Os
  39 .Sh NAME
  40 .Nm getgrent ,
  41 .Nm getgrnam ,
  42 .Nm getgrgid ,
  43 .Nm setgroupent ,
  44 .\" .Nm setgrfile ,
  45 .Nm setgrent ,
  46 .Nm endgrent
  47 .Nd group database operations
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In sys/types.h
  52 .In grp.h
  53 .Ft struct group *
  54 .Fn getgrent void
  55 .Ft struct group *
  56 .Fn getgrnam "const char *name"
  57 .Ft struct group *
  58 .Fn getgrgid "gid_t gid"
  59 .Ft int
  60 .Fn setgroupent "int stayopen"
  61 .\" .Ft void
  62 .\" .Fn setgrfile "const char *name"
  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 .Pa /etc/group
  70 which is described
  71 in
  72 .Xr group 5 .
  73 Each line of the database is defined by the structure
  74 .Vt group
  75 found in the include
  76 file
  77 .Aq Pa grp.h :
  78 .Bd -literal -offset indent
  79 struct group {
  80         char    *gr_name;       /* group name */
  81         char    *gr_passwd;     /* group password */
  82         int     gr_gid;         /* group id */
  83         char    **gr_mem;       /* group members */
  84 };
  85 .Ed
  86 .Pp
  87 The functions
  88 .Fn getgrnam
  89 and
  90 .Fn getgrgid
  91 search the group database for the given group name pointed to by
  92 .Fa name
  93 or the group id pointed to by
  94 .Fa gid ,
  95 respectively, returning the first one encountered.  Identical group
  96 names or group gids may result in undefined behavior.
  97 .Pp
  98 The
  99 .Fn getgrent
 100 function
 101 sequentially reads the group database and is intended for programs
 102 that wish to step through the complete list of groups.
 103 .Pp
 104 All three routines will open the group file for reading, if necessary.
 105 .Pp
 106 The
 107 .Fn setgroupent
 108 function
 109 opens the file, or rewinds it if it is already open.  If
 110 .Fa stayopen
 111 is non-zero, file descriptors are left open, significantly speeding
 112 functions subsequent calls.  This functionality is unnecessary for
 113 .Fn getgrent
 114 as it doesn't close its file descriptors by default.  It should also
 115 be noted that it is dangerous for long-running programs to use this
 116 functionality as the group file may be updated.
 117 .Pp
 118 The
 119 .Fn setgrent
 120 function
 121 is identical to
 122 .Fn setgroupent
 123 with an argument of zero.
 124 .Pp
 125 The
 126 .Fn endgrent
 127 function
 128 closes any open files.
 129 .Sh YP/NIS INTERACTION
 130 When the
 131 .Xr yp 8
 132 group database is enabled, the
 133 .Fn getgrnam
 134 and
 135 .Fn getgrgid
 136 functions use the YP maps
 137 .Dq Li group.byname
 138 and
 139 .Dq Li group.bygid ,
 140 respectively, if the requested group is not found in the local
 141 .Pa /etc/group
 142 file.  The
 143 .Fn getgrent
 144 function will step through the YP map
 145 .Dq Li group.byname
 146 if the entire map is enabled as described in
 147 .Xr group 5 .
 148 .Sh RETURN VALUES
 149 The functions
 150 .Fn getgrent ,
 151 .Fn getgrnam ,
 152 and
 153 .Fn getgrgid ,
 154 return a pointer to the group entry if successful; if end-of-file
 155 is reached or an error occurs a null pointer is returned.
 156 The functions
 157 .Fn setgroupent
 158 and
 159 .Fn setgrent
 160 return the value 1 if successful, otherwise the value
 161 0 is returned.
 162 The functions
 163 .Fn endgrent
 164 and
 165 .Fn setgrfile
 166 have no return value.
 167 .Sh FILES
 168 .Bl -tag -width /etc/group -compact
 169 .It Pa /etc/group
 170 group database file
 171 .El
 172 .Sh COMPATIBILITY
 173 The historic function
 174 .Fn setgrfile ,
 175 which allowed the specification of alternate password databases, has
 176 been deprecated and is no longer available.
 177 .Sh SEE ALSO
 178 .Xr getpwent 3 ,
 179 .Xr group 5 ,
 180 .Xr yp 8
 181 .Sh HISTORY
 182 The functions
 183 .Fn endgrent ,
 184 .Fn getgrent ,
 185 .Fn getgrnam ,
 186 .Fn getgrgid ,
 187 and
 188 .Fn setgrent
 189 appeared in
 190 .At v7 .
 191 The functions
 192 .Fn setgrfile
 193 and
 194 .Fn setgroupent
 195 appeared in
 196 .Bx 4.3 Reno .
 197 .Sh BUGS
 198 The functions
 199 .Fn getgrent ,
 200 .Fn getgrnam ,
 201 .Fn getgrgid ,
 202 .Fn setgroupent
 203 and
 204 .Fn setgrent
 205 leave their results in an internal static object and return
 206 a pointer to that object.
 207 Subsequent calls to
 208 the same function
 209 will modify the same object.