PW_LOCK(3) | Library Functions Manual | PW_LOCK(3)

# NAME

`pw_lock`, `pw_mkdb`, `pw_abort` — passwd file update functions

# SYNOPSIS

System Utilities Library (libutil, -lutil)
`#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)

June 6, 2025 | Debian