February 17, 2007 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

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