OpenBSD manual page server

Manual Page Search Parameters

PW_LOCK(3) Library Functions Manual PW_LOCK(3)

pw_lock, pw_mkdb, pw_abortpasswd file update functions

#include <util.h>

int
pw_lock(int retries);

int
pw_mkdb(char *username, int pwflags);

void
pw_abort(void);

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

The () 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. A different lock file can be specified with pw_file(3).

pw_init(3) must be called before ().

The () 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:

only update the secure database file (/etc/spwd.db).
do not update the legacy password file (/etc/passwd).

By default the secure and insecure password databases and the legacy password file /etc/passwd are updated. You should finish writing to and close the file descriptor returned by () 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 () function aborts a passwd file update by deleting /etc/ptmp. The passwd database remains unchanged.

The pw_lock() function returns -1 on error and sets errno. The pw_mkdb() function returns -1 if it is unable to complete properly.

/etc/master.passwd
Current password file.
/etc/passwd
Legacy password file.
/etc/ptmp
Password lock file.
/etc/pwd.db
Insecure password database file.
/etc/spwd.db
Secure password database file.

[]
pw_lock() was called before pw_init(3).

pw_lock() may also fail and set errno for any of the errors specified for the routine open(2).

pw_file(3), pw_init(3), pwd_mkdb(8)

August 14, 2016 OpenBSD-current