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
#include <pwd.h>
#include <util.h>
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)