NAME    [Toc]    [Back]

     pw_lock, pw_mkdb, pw_abort - passwd file update functions

SYNOPSIS    [Toc]    [Back]

     #include <util.h>

     int
     pw_lock(int retries);

     int
     pw_mkdb(char *username, int pwflags);

     void
     pw_abort();

DESCRIPTION    [Toc]    [Back]

     The pw_lock(), pw_mkdb(), and pw_abort() functions  allow  a
program to update
 the system passwd database.

     The  pw_lock() function attempts to lock the passwd database
by creating
     the file /etc/ptmp with an exclusive  lock  (using  flock(2)
semantics) and
     returns  the  file  descriptor  of that file.  If retries is
greater than zero,
 pw_lock() will try multiple  times  to  open  /etc/ptmp,
waiting one second
  between  tries.   In  addition  to  being  a lock file,
/etc/ptmp will also
     hold the contents of the new passwd file.

     The pw_mkdb() function updates the passwd file from the contents of
     /etc/ptmp via pwd_mkdb(8).  If a username is specified, only
the record
     for the specified user will be  updated.   The  pwflags  are
specified by
     OR'ing the following values:

         _PASSWORD_SECUREONLY   only  update  the secure database
file
                               (/etc/spwd.db).
         _PASSWORD_OMITV7      do not update the Version 7 format
password
                               file  (/etc/passwd).

     By  default  the secure, insecure and Version 7 format password databases
     are updated.  You should finish writing  to  and  close  the
file descriptor
     returned   by   pw_lock()   before  calling  pw_mkdb().   If
pw_mkdb() fails and
     you do not wish to retry,  you  should  make  sure  to  call
pw_abort() to
     clean up the lock file.

     The  pw_abort()  function  aborts  a  passwd  file update by
deleting
     /etc/ptmp.  The passwd database remains unchanged.

RETURN VALUES    [Toc]    [Back]

     The pw_lock() and pw_mkdb() functions return -1 if they  are
unable to
     complete properly.

FILES    [Toc]    [Back]

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

SEE ALSO    [Toc]    [Back]

     flock(2), pw_init(3), pwd_mkdb(8)

OpenBSD      3.6                          August     20,     2001