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