August 1, 2004 PW_INIT 3

### NAME

pw_init, pw_edit, pw_prompt, pw_copy, pw_copyx, pw_scan, pw_error - utility functions for interactive passwd file updates

### LIBRARY

System Utilities Library (libutil, -lutil)

### SYNOPSIS

```void` pw_init(```void`)
```void` pw_edit(```int notsetuid``, const char *filename`)
```void` pw_prompt(```void`)
```void` pw_copy(```int ffd``, int tfd``, struct passwd *pw``, struct passwd *old_pw`)
```int` pw_copyx(```int ffd``, int tfd``, struct passwd *pw``, struct passwd *old_pw``, char *errbuf``, size_t errbufsz`)
```int` pw_scan(```char *bp``, struct passwd *pw``, int *flags`)
```void` pw_error(```const char *name``, int err``, int eval`)

### DESCRIPTION

These functions are designed as conveniences for interactive programs which update the passwd file and do nothing else. They generally handle errors by printing out a message to the standard error stream and possibly aborting the process.

The pw_init(``) function prepares for a passwd update by unlimiting all resource constraints, disabling core dumps (thus preventing dumping the contents of the passwd database into a world-readable file), and disabling most signals.

The pw_edit(``) function runs an editor (named by the environment variable EDITOR, or ```/usr/bin/vi` if EDITOR is not set) on the file ```filename` (or ```/etc/ptmp` if ```filename` is NULL). If ```notsetuid` is nonzero, pw_edit(``) will set the effective user and group ID to the real user and group ID before running the editor.

The pw_prompt(``) function asks the user whether he or she wants to re-edit the password file; if the answer is no, pw_prompt(``) deletes the lock file and exits the process.

The pw_copy(``) function reads a passwd file from ```ffd` and writes it to ```tfd`, updating the entry corresponding to pw->pw_name with the information in ```pw`. If ```old_pw` is not NULL, it checks to make sure the old entry is the same as the one described in ```old_pw` or the process is aborted. If an entry is not found to match ```pw`, a new entry is appended to the passwd file only if the real user ID is 0. If an error occurs, pw_copy(``) will display a message on ```stderr` and call pw_error(``).

The pw_copyx(``) function performs the same operation as pw_copy(``) with the exception of error handling. Upon an error, pw_copyx(``) will write an error message into the buffer pointed to by ```errbuf` which has the size ```errbufsz`.

The pw_scan(``) function accepts in ```bp` a passwd entry as it would be represented in ```/etc/master.passwd` and fills in ```pw` with corresponding values; string fields in ```pw` will be pointers into ```bp`. Some characters in ```bp` will be overwritten with 0s in order to terminate the strings pointed to by ```pw`. If ```flags` is non-null, it should be cleared and the following options enabled if required:

```_PASSWORD_NOWARN`
  Don't print warnings.

```_PASSWORD_OLDFMT`
  Parse ```bp` as an old format entry as found in ```/etc/passwd`.

Upon return it is cleared, and filled in with the following flags:

```_PASSWORD_NOUID`
  The uid field of ```bp` is empty.

```_PASSWORD_NOGID`
  The gid field of ```bp` is empty.

```_PASSWORD_NOCHG`
  The change field of ```bp` is empty.

```_PASSWORD_NOEXP`
  The expire field of ```bp` is empty.

The pw_error(``) function displays an error message, aborts the current passwd update, and exits the current process. If ```err` is non-zero, a warning message beginning with ```name` is printed for the current value of errno. The process exits with status ```eval`.

### RETURN VALUES

The pw_copyx(``) function returns 1 if the new password entry was successfully written to the destination file, and 0 otherwise.

The pw_scan(``) function prints a warning message and returns 0 if the string in the ```bp` argument is not a valid passwd string. Otherwise, pw_scan(``) returns 1.

### FILES

```/etc/master.passwd`
```/etc/ptmp`

### SEE ALSO

pw_lock(3), passwd(5)