lib/libc/gen/getpwent.3

   1 .\" Copyright (c) 1988, 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: @(#)getpwent.3    8.2 (Berkeley) 12/11/93
  33 .\"     $Id$
  34 .\"
  35 .Dd September 20, 1994
  36 .Dt GETPWENT 3
  37 .Os
  38 .Sh NAME
  39 .Nm getpwent ,
  40 .Nm getpwnam ,
  41 .Nm getpwuid ,
  42 .Nm setpassent ,
  43 .Nm setpwent ,
  44 .Nm endpwent
  45 .Nd password database operations
  46 .Sh SYNOPSIS
  47 .Fd #include <sys/types.h>
  48 .Fd #include <pwd.h>
  49 .Ft struct passwd *
  50 .Fn getpwent void
  51 .Ft struct passwd *
  52 .Fn getpwnam "const char *login"
  53 .Ft struct passwd *
  54 .Fn getpwuid "uid_t uid"
  55 .Ft int
  56 .Fn setpassent "int  stayopen"
  57 .Ft void
  58 .Fn setpwent void
  59 .Ft void
  60 .Fn endpwent void
  61 .Sh DESCRIPTION
  62 These functions
  63 operate on the password database file
  64 which is described
  65 in
  66 .Xr passwd 5 .
  67 Each entry in the database is defined by the structure
  68 .Ar passwd
  69 found in the include
  70 file
  71 .Aq Pa pwd.h :
  72 .Bd -literal -offset indent
  73 struct passwd {
  74         char    *pw_name;       /* user name */
  75         char    *pw_passwd;     /* encrypted password */
  76         uid_t   pw_uid;         /* user uid */
  77         gid_t   pw_gid;         /* user gid */
  78         time_t  pw_change;      /* password change time */
  79         char    *pw_class;      /* user access class */
  80         char    *pw_gecos;      /* Honeywell login info */
  81         char    *pw_dir;        /* home directory */
  82         char    *pw_shell;      /* default shell */
  83         time_t  pw_expire;      /* account expiration */
  84         int     pw_fields;      /* internal: fields filled in */
  85 };
  86 .Ed
  87 .Pp
  88 The functions
  89 .Fn getpwnam
  90 and
  91 .Fn getpwuid
  92 search the password database for the given login name or user uid,
  93 respectively, always returning the first one encountered.
  94 .Pp
  95 The
  96 .Fn getpwent
  97 function
  98 sequentially reads the password database and is intended for programs
  99 that wish to process the complete list of users.
 100 .Pp
 101 The
 102 .Fn setpassent
 103 function
 104 accomplishes two purposes.
 105 First, it causes
 106 .Fn getpwent
 107 to ``rewind'' to the beginning of the database.
 108 Additionally, if
 109 .Fa stayopen
 110 is non-zero, file descriptors are left open, significantly speeding
 111 up subsequent accesses for all of the routines.
 112 (This latter functionality is unnecessary for
 113 .Fn getpwent
 114 as it doesn't close its file descriptors by default.)
 115 .Pp
 116 It is dangerous for long-running programs to keep the file descriptors
 117 open as the database will become out of date if it is updated while the
 118 program is running.
 119 .Pp
 120 The
 121 .Fn setpwent
 122 function
 123 is identical to
 124 .Fn setpassent
 125 with an argument of zero.
 126 .Pp
 127 The
 128 .Fn endpwent
 129 function
 130 closes any open files.
 131 .Pp
 132 These routines have been written to ``shadow'' the password file, e.g.
 133 allow only certain programs to have access to the encrypted password.
 134 If the process which calls them has an effective uid of 0, the encrypted
 135 password will be returned, otherwise, the password field of the returned
 136 structure will point to the string
 137 .Ql * .
 138 .Sh YP/NIS INTERACTION
 139 When the
 140 .Xr yp 4
 141 password database is enabled, the
 142 .Fn getpwnam
 143 and
 144 .Fn getpwuid
 145 functions use the YP maps
 146 .Dq Li passwd.byname
 147 and
 148 .Dq Li passwd.byuid ,
 149 respectively, if the requested password entry is not found in the
 150 local database.  The
 151 .Fn getpwent
 152 function will step through the YP map
 153 .Dq Li passwd.byname
 154 if the entire map is enabled as described in
 155 .Xr passwd 5 .
 156 .Sh RETURN VALUES
 157 The functions
 158 .Fn getpwent ,
 159 .Fn getpwnam ,
 160 and
 161 .Fn getpwuid ,
 162 return a valid pointer to a passwd structure on success
 163 and a null pointer if end-of-file is reached or an error occurs.
 164 The
 165 .Fn setpassent
 166 function returns 0 on failure and 1 on success.
 167 The
 168 .Fn endpwent
 169 and
 170 .Fn setpwent
 171 functions
 172 have no return value.
 173 .Sh FILES
 174 .Bl -tag -width /etc/master.passwd -compact
 175 .It Pa /etc/pwd.db
 176 The insecure password database file
 177 .It Pa /etc/spwd.db
 178 The secure password database file
 179 .It Pa /etc/master.passwd
 180 The current password file
 181 .It Pa /etc/passwd
 182 A Version 7 format password file
 183 .El
 184 .Sh SEE ALSO
 185 .Xr getlogin 2 ,
 186 .Xr getgrent 3 ,
 187 .Xr yp 4 ,
 188 .Xr passwd 5 ,
 189 .Xr pwd_mkdb 8 ,
 190 .Xr vipw 8
 191 .Sh HISTORY
 192 The
 193 .Fn getpwent ,
 194 .Fn getpwnam ,
 195 .Fn getpwuid ,
 196 .Fn setpwent,
 197 and
 198 .Fn endpwent
 199 functions appeared in
 200 .At v7 .
 201 The
 202 .Fn setpassent
 203 function appeared in
 204 .Bx 4.3 Reno .
 205 .Sh COMPATIBILITY
 206 The historic function
 207 .Xr setpwfile 3 ,
 208 which allowed the specification of alternate password databases,
 209 has been deprecated and is no longer available.
 210 .Sh BUGS
 211 The functions
 212 .Fn getpwent ,
 213 .Fn getpwnam ,
 214 and
 215 .Fn getpwuid ,
 216 leave their results in an internal static object and return
 217 a pointer to that object. Subsequent calls to
 218 the same function
 219 will modify the same object.