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.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 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 .Ar 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 .Ar name
  92 or the group id pointed to by
  93 .Ar 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 RETURN VALUES
 129 The functions
 130 .Fn getgrent ,
 131 .Fn getgrnam ,
 132 and
 133 .Fn getgrgid ,
 134 return a pointer to the group entry if successful; if end-of-file
 135 is reached or an error occurs a null pointer is returned.
 136 The functions
 137 .Fn setgroupent
 138 and
 139 .Fn setgrent
 140 return the value 1 if successful, otherwise the value
 141 0 is returned.
 142 The functions
 143 .Fn endgrent
 144 and
 145 .Fn setgrfile
 146 have no return value.
 147 .Sh FILES
 148 .Bl -tag -width /etc/group -compact
 149 .It Pa /etc/group
 150 group database file
 151 .El
 152 .Sh SEE ALSO
 153 .Xr getpwent 3 ,
 154 .Xr yp 4 ,
 155 .Xr group 5
 156 .Sh HISTORY
 157 The functions
 158 .Fn endgrent ,
 159 .Fn getgrent ,
 160 .Fn getgrnam ,
 161 .Fn getgrgid ,
 162 and
 163 .Fn setgrent
 164 appeared in
 165 .At v7 .
 166 The functions
 167 .Fn setgrfile
 168 and
 169 .Fn setgroupent
 170 appeared in
 171 .Bx 4.3 Reno .
 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 BUGS
 178 The functions
 179 .Fn getgrent ,
 180 .Fn getgrnam ,
 181 .Fn getgrgid ,
 182 .Fn setgroupent
 183 and
 184 .Fn setgrent
 185 leave their results in an internal static object and return
 186 a pointer to that object.
 187 Subsequent calls to
 188 the same function
 189 will modify the same object.
 190 .Pp
 191 The functions
 192 .Fn getgrent ,
 193 .Fn endgrent ,
 194 .Fn setgroupent ,
 195 and
 196 .Fn setgrent
 197 are fairly useless in a networked environment and should be
 198 avoided, if possible.