*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> setpwfile (3)              



NAME    [Toc]    [Back]

     getpwent, getpwnam, getpwuid, setpassent, setpwent, endpwent
- password
     database operations

SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <pwd.h>

     struct passwd *

     struct passwd *
     getpwnam(const char *login);

     struct passwd *
     getpwuid(uid_t uid);

     setpassent(int stayopen);



DESCRIPTION    [Toc]    [Back]

     These  functions operate on the password database file which
is described
     in passwd(5).  Each entry in the database is defined by  the
     struct passwd found in the include file <pwd.h>:

           struct passwd {
                   char    *pw_name;       /* user name */
                   char     *pw_passwd;     /* encrypted password
                   uid_t   pw_uid;         /* user uid */
                   gid_t   pw_gid;         /* user gid */
                   time_t   pw_change;       /*  password  change
time */
                   char     *pw_class;       /* user access class
                   char    *pw_gecos;      /* Honeywell login info */
                   char    *pw_dir;        /* home directory */
                   char    *pw_shell;      /* default shell */
                   time_t   pw_expire;      /* account expiration

     The functions getpwnam() and getpwuid() search the  password
database for
     the  given  login  name or user ID, respectively, always returning the first
     one encountered.

     getpwent() sequentially reads the password database  and  is
intended for
     programs that wish to process the complete list of users.

     setpassent()  accomplishes  two  purposes.  First, it causes
getpwent() to
     ``rewind'' to the beginning of the database.   Additionally,
if stayopen
     is  non-zero,  file descriptors are left open, significantly
speeding up
     subsequent accesses for all of the routines.   (This  latter
     is  unnecessary  for getpwent() as it doesn't close its file
descriptors by

     It is dangerous for long-running programs to keep  the  file
     open as the database will become out of date if it is updated while the
     program is running.

     setpwent() is equivalent to setpassent() with an argument of

     The endpwent() function closes any open files.

     These  routines have been written to ``shadow'' the password
file, e.g.,
     allow only certain programs to have access to the  encrypted
password.  If
     the  process  which  calls them has an effective UID of 0 or
has the
     ``_shadow'' group in its group vector, the  encrypted  password will be returned,
 otherwise, the password field of the returned structure will
     point to the string `*'.

RETURN VALUES    [Toc]    [Back]

     The functions getpwent(), getpwnam(), and getpwuid()  return
a valid
     pointer  to  a passwd structure on success or a null pointer
if end-of-file
     is reached or an error occurs.   The  setpassent()  function
returns 0 on
     failure  or  1  on  success.   The endpwent() and setpwent()
functions have no
     return value.

FILES    [Toc]    [Back]

     /etc/pwd.db         insecure password database file
     /etc/spwd.db        secure password database file
     /etc/master.passwd  current password file
     /etc/passwd         a Version 7 format password file

SEE ALSO    [Toc]    [Back]

     getlogin(2), getgrent(3), pw_dup(3), passwd(5), pwd_mkdb(8),

HISTORY    [Toc]    [Back]

     The  getpwent(),  getpwnam(),  getpwuid(),  setpwent(),  and
endpwent() functions
 appeared in Version 7  AT&T  UNIX.   The  setpassent()
function appeared
 in 4.3BSD-Reno.

     The historic function setpwfile(3), which allowed the specification of
     alternate password databases, has been deprecated and is  no
longer available.

BUGS    [Toc]    [Back]

     The  functions  getpwent(), getpwnam(), and getpwuid() leave
their results
     in an internal static object and return a  pointer  to  that
object.  Subsequent
  calls  to any of these functions will modify the same

     The  routines  getpwent(),  endpwent(),  setpassent(),   and
setpwent() are
     fairly  useless  in  a  networked  environment and should be
avoided, if possible.

OpenBSD     3.6                        December     11,      1993
[ Back ]
 Similar pages
Name OS Title
yppasswd Linux change your password in the NIS database
skey OpenBSD one-time password user database
printpw Tru64 Outputs the contents of the password database
yppasswd IRIX update user password in NIS database
getprpw HP-UX display protected password database
modprpw HP-UX modify protected password database
prpasswd Tru64 Protected password authentication database (Enhanced Security)
prpwd Tru64 Protected password authentication database (Enhanced Security)
endprpwent HP-UX manipulate protected password database entries (for trusted systems only).
getprpwaid HP-UX manipulate protected password database entries (for trusted systems only).
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service