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