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.