NAME    [Toc]    [Back]

     pw_lock, pw_mkdb, pw_abort, pw_setprefix, pw_getprefix - passwd file
     update functions

LIBRARY    [Toc]    [Back]

     System Utilities Library (libutil, -lutil)

SYNOPSIS    [Toc]    [Back]

     #include <util.h>

     int
     pw_lock(int retries);

     int
     pw_mkdb(const char *username, int secureonly);

     void
     pw_abort(void);

     void
     pw_error(const char *name, int err, int eval);

     int
     pw_setprefix(const char *new_prefix);

     const char *
     pw_getprefix(void);

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, 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.  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.  If the username argument is not NULL, only
     database entries pertaining to the specified user will be modified.  If
     the secureonly argument is non-zero, only the secure database will be
     updated.

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

     The pw_setprefix() function defines the root directory used for passwd
     file updates. If the prefix is set to /newroot pw_lock() will operate on
     /newroot/etc/ptmp afterwards. The default prefix is an empty string.

     The pw_getprefix() function returns the root directory which is currently
     used for passwd file updates.

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
     /etc/ptmp

SEE ALSO    [Toc]    [Back]

     pw_init(3), pwd_mkdb(8)

BSD                             August 18, 2001                            BSD