PW_INIT(3) | Library Functions Manual | PW_INIT(3)

# NAME

`pw_init`, `pw_setdir`, `pw_file`, `pw_edit`, `pw_prompt`, `pw_copy`, `pw_scan`, `pw_error` — utility functions for interactive passwd file updates

# SYNOPSIS

System Utilities Library (libutil, -lutil)
`#include <pwd.h>`
`#include <util.h>`

void
`pw_init`(void);

void
`pw_setdir`(const char *directory);

char *
`pw_file`(const char *filename);

void
`pw_edit`(int notsetuid, const char *filename);

void
`pw_prompt`(void);

void
`pw_copy`(int ffd, int tfd, const struct passwd *pw, const struct passwd *opw);

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_setdir`() function sets an alternative directory where the rest of the functions look for password-related files. Use this if you are writing utilities that should be able to handle password files outside of /etc.

The `pw_file`() function transforms filenames so that they end up in the directory specified to the latest `pw_setdir`() call. The rule is that all directories are stripped of the given name and only the filename is appended to the directory.

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 they want 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 opw is not NULL, opw->pw_name will be used for matching instead. Additionally, if the existing entry does not match opw, the operation is aborted. The use of opw allows the caller to change the user name in an entry as well as guarantee that the entry being replaced has not changed in the meantime.

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 is filled in with the following flags:

`_PASSWORD_NOUID`
  The uid field of bp is empty.
`_PASSWORD_NOGID`
  The gid field of bp is empty.
`_PASSWD_NOCHG`
  The change field of bp is empty.
`_PASSWD_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_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
  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.

# SEE ALSO

pw_lock(3), passwd(5)

June 6, 2025 | Debian