NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #include <pwd.h>
     #include <util.h>

     void
     pw_init();

     void
     pw_setdir(const char *directory);

     char *
     pw_file(const char *filename);

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

     void
     pw_prompt();

     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    [Toc]    [Back]

     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  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 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    [Toc]    [Back]

     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    [Toc]    [Back]

     /etc/master.passwd
     /etc/ptmp

SEE ALSO    [Toc]    [Back]

     pw_lock(3), passwd(5)

OpenBSD     3.6                        December     15,      1995