.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PasswdFile 3pm"
.TH PasswdFile 3pm "2021-08-21" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Unix::PasswdFile \- Perl interface to /etc/passwd format files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Unix::PasswdFile;
\&
\&  $pw = new Unix::PasswdFile "/etc/passwd";
\&  $pw\->user("joeblow", $pw\->encpass("secret"), $pw\->maxuid + 1, 10,
\&            "Joe Blow", "/export/home/joeblow", "/bin/ksh");
\&  $pw\->delete("deadguy");
\&  $pw\->passwd("johndoe", $pw\->encpass("newpass"));
\&  foreach $user ($pw\->users) {
\&      print "Username: $user, Full Name: ", $pw\->gecos($user), "\en";
\&  }
\&  $pw\->commit();
\&  undef $pw;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Unix::PasswdFile module provides an abstract interface to /etc/passwd
format files.  It automatically handles file locking, getting colons in the
right places, and all the other niggling details.
.SH "METHODS"
.IX Header "METHODS"
.SS "commit( [\s-1BACKUPEXT\s0] )"
.IX Subsection "commit( [BACKUPEXT] )"
See the Unix::ConfigFile documentation for a description of this method.
.SS "delete( \s-1USERNAME\s0 )"
.IX Subsection "delete( USERNAME )"
This method will delete the named user.  It has no effect if the supplied user
does not exist.
.SS "encpass( \s-1PASSWORD\s0 )"
.IX Subsection "encpass( PASSWORD )"
See the Unix::ConfigFile documentation for a description of this method.
.SS "gecos( \s-1USERNAME\s0 [,GECOS] )"
.IX Subsection "gecos( USERNAME [,GECOS] )"
Read or modify a user's \s-1GECOS\s0 string (typically their full name).  Returns
the \s-1GECOS\s0 string in either case.
.SS "gid( \s-1USERNAME\s0 [,GID] )"
.IX Subsection "gid( USERNAME [,GID] )"
Read or modify a user's \s-1GID.\s0  Returns the \s-1GID\s0 in either case.
.SS "home( \s-1USERNAME\s0 [,HOMEDIR] )"
.IX Subsection "home( USERNAME [,HOMEDIR] )"
Read or modify a user's home directory.  Returns the home directory in either
case.
.SS "maxuid( [\s-1IGNORE\s0] )"
.IX Subsection "maxuid( [IGNORE] )"
This method returns the maximum \s-1UID\s0 in use by all users.  If you pass in the
optional \s-1IGNORE\s0 parameter, it will ignore all UIDs greater or equal to \s-1IGNORE\s0
when doing this calculation.  This is useful for excluding accounts like
nobody.
.SS "new( \s-1FILENAME\s0 [,OPTIONS] )"
.IX Subsection "new( FILENAME [,OPTIONS] )"
See the Unix::ConfigFile documentation for a description of this method.
.SS "passwd( \s-1USERNAME\s0 [,PASSWD] )"
.IX Subsection "passwd( USERNAME [,PASSWD] )"
Read or modify a user's password.  Returns the encrypted password in either
case.  If you have a plaintext password, use the encpass method to encrypt it
before passing it to this method.
.SS "rename( \s-1OLDNAME, NEWNAME\s0 )"
.IX Subsection "rename( OLDNAME, NEWNAME )"
This method changes the username for a user.  If \s-1NEWNAME\s0 corresponds to an
existing user, that user will be overwritten.  It returns 0 on failure and 1
on success.
.SS "shell( \s-1USERNAME\s0 [,SHELL] )"
.IX Subsection "shell( USERNAME [,SHELL] )"
Read or modify a user's shell.  Returns the shell in either case.
.SS "uid( \s-1USERNAME\s0 [,UID] )"
.IX Subsection "uid( USERNAME [,UID] )"
Read or modify a user's \s-1UID.\s0  Returns the \s-1UID\s0 in either case.
.SS "user( \s-1USERNAME\s0 [,PASSWD, \s-1UID, GID, GECOS, HOMEDIR, SHELL\s0] )"
.IX Subsection "user( USERNAME [,PASSWD, UID, GID, GECOS, HOMEDIR, SHELL] )"
This method can add, modify, or return information about a user.  Supplied
with a single username parameter, it will return a six element list consisting
of (\s-1PASSWORD, UID, GID, GECOS, HOMEDIR, SHELL\s0), or undef if no such user
exists.  If you supply all seven parameters, the named user will be created
or modified if it already exists.  The six element list is also returned to
you in this case.
.SS "users( [\s-1SORTBY\s0] )"
.IX Subsection "users( [SORTBY] )"
This method returns a list of all existing usernames.  By default the list
will be sorted in order of the UIDs of the users.  You may also supply \*(L"name\*(R"
as a parameter to the method to get the list sorted by username.  In scalar
context, this method returns the total number of users.
.SH "AUTHOR"
.IX Header "AUTHOR"
Steve Snodgrass, ssnodgra@fore.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Unix::AliasFile, Unix::AutomountFile, Unix::ConfigFile, Unix::GroupFile