Manual Page Result
0
Command: pw_lock | Section: 3 | Source: OpenBSD | File: pw_lock.3
PW_LOCK(3) FreeBSD Library Functions Manual PW_LOCK(3)
NAME
pw_lock, pw_mkdb, pw_abort - passwd file update functions
SYNOPSIS
#include <util.h>
int
pw_lock(int retries);
int
pw_mkdb(char *username, int pwflags);
void
pw_abort(void);
DESCRIPTION
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. A
different lock file can be specified with pw_file(3).
pw_init(3) must be called before pw_lock().
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 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 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
The pw_lock() function returns -1 on error and sets errno. The pw_mkdb()
function returns -1 if it is unable to complete properly.
FILES
/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.
ERRORS
[EINVAL] 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).
SEE ALSO
pw_file(3), pw_init(3), pwd_mkdb(8)
FreeBSD 14.1-RELEASE-p8 August 14, 2016 FreeBSD 14.1-RELEASE-p8