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