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

# NAME

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

# LIBRARY

System Utilities Library (libutil, -lutil)

# SYNOPSIS

`#include <util.h>`

int
`pw_lock`(int retries);

int
`pw_mkdb`(const char *username, int secureonly);

void
`pw_abort`(void);

int
`pw_setprefix`(const char *new_prefix);

const char *
`pw_getprefix`(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.

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.

# RETURN VALUES

The `pw_lock`() and `pw_mkdb`() functions return -1 if they are unable to complete properly.

# FILES

/etc/master.passwd
/etc/ptmp

# SEE ALSO

pw_init(3), pwd_mkdb(8)

February 17, 2007 | NetBSD 9.5