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).