.\" 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 "Passwd::Unix 3pm"
.TH Passwd::Unix 3pm "2021-01-07" "perl v5.32.0" "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"
Passwd::Unix \- access to standard unix files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Passwd::Unix;
\&        
\&        my $pu = Passwd::Unix\->new();
\&        my $err = $pu\->user("example", $pu\->encpass("my_secret"), $pu\->maxuid + 1, 10,
\&                                                "My User", "/home/example", "/bin/bash" );
\&        $pu\->passwd("example", $pu\->encpass("newsecret"));
\&        foreach my $user ($pu\->users) {
\&                print "Username: $user\enFull Name: ", $pu\->gecos($user), "\en\en";
\&        }
\&        my $uid = $pu\->uid(\*(Aqexample\*(Aq);
\&        $pu\->del("example");
\&
\&        # or 
\&
\&        use Passwd::Unix qw(check_sanity reset encpass passwd_file shadow_file 
\&                                group_file backup warnings del del_user uid gid gecos
\&                                home shell passwd rename maxgid maxuid exists_user 
\&                                exists_group user users users_from_shadow del_group 
\&                                group groups groups_from_gshadow);
\&        
\&        my $err = user( "example", encpass("my_secret"), $pu\->maxuid + 1, 10,
\&                                        "My User", "/home/example", "/bin/bash" );
\&        passwd("example",encpass("newsecret"));
\&        foreach my $user (users()) {
\&                print "Username: $user\enFull Name: ", gecos($user), "\en\en";
\&        }
\&        my $uid = uid(\*(Aqexample\*(Aq);
\&        del("example");
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
Passwd::Unix provides an abstract object-oriented and function interface to
standard Unix files, such as /etc/passwd, /etc/shadow, /etc/group. Additionally
this module provides  environment to testing new software, without using
system critical files in /etc/dir.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Passwd::Unix module provides an abstract interface to /etc/passwd, 
/etc/shadow and /etc/group format files. It is inspired by 
Unix::PasswdFile module (that one does not handle /etc/shadow file, 
what is necessary in modern systems like Sun Solaris 10 or Linux).
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.IP "\fBnew( [ param0 =\fR 1, param1 => 0... ] )>" 4
.IX Item "new( [ param0 = 1, param1 => 0... ] )>"
Constructor. Possible parameters are:
.RS 4
.ie n .IP "\fBpasswd\fR \- path to passwd file; default ""/etc/passwd""" 8
.el .IP "\fBpasswd\fR \- path to passwd file; default \f(CW/etc/passwd\fR" 8
.IX Item "passwd - path to passwd file; default /etc/passwd"
.PD 0
.ie n .IP "\fBshadow\fR \- path to shadow file; default ""/etc/shadow""" 8
.el .IP "\fBshadow\fR \- path to shadow file; default \f(CW/etc/shadow\fR" 8
.IX Item "shadow - path to shadow file; default /etc/shadow"
.ie n .IP "\fBgroup\fR \- path to group file; default ""/etc/group""" 8
.el .IP "\fBgroup\fR \- path to group file; default \f(CW/etc/group\fR" 8
.IX Item "group - path to group file; default /etc/group"
.ie n .IP "\fBgshadow\fR \- path to gshadow file if any; default ""/etc/gshadow""" 8
.el .IP "\fBgshadow\fR \- path to gshadow file if any; default \f(CW/etc/gshadow\fR" 8
.IX Item "gshadow - path to gshadow file if any; default /etc/gshadow"
.ie n .IP "\fBumask\fR \- umask for creating files; default 0022 (standard for \s-1UNIX\s0 and Linux systems)" 8
.el .IP "\fBumask\fR \- umask for creating files; default \f(CW0022\fR (standard for \s-1UNIX\s0 and Linux systems)" 8
.IX Item "umask - umask for creating files; default 0022 (standard for UNIX and Linux systems)"
.ie n .IP "\fBbackup\fR \- boolean; if set to 1, backup will be made; default 1" 8
.el .IP "\fBbackup\fR \- boolean; if set to \f(CW1\fR, backup will be made; default \f(CW1\fR" 8
.IX Item "backup - boolean; if set to 1, backup will be made; default 1"
.ie n .IP "\fBwarnings\fR \- boolean; if set to 1, important warnings will be displayed; default 0" 8
.el .IP "\fBwarnings\fR \- boolean; if set to \f(CW1\fR, important warnings will be displayed; default \f(CW0\fR" 8
.IX Item "warnings - boolean; if set to 1, important warnings will be displayed; default 0"
.RE
.RS 4
.RE
.IP "\fB\fBcheck_sanity()\fB\fR" 4
.IX Item "check_sanity()"
.PD
This method check if environment is sane. I.e. if users in \fIshadow\fR and
in \fIpasswd\fR are the same. This method is invoked in constructor.
.IP "\fBdel( \s-1USERNAME0, USERNAME1...\s0 )\fR" 4
.IX Item "del( USERNAME0, USERNAME1... )"
This method is an alias for \f(CW\*(C`del_user\*(C'\fR. It's for transition only.
.IP "\fBdel_user( \s-1USERNAME0, USERNAME1...\s0 )\fR" 4
.IX Item "del_user( USERNAME0, USERNAME1... )"
This method will delete the list of users. It has no effect if the 
supplied users do not exist.
.IP "\fBdel_group( \s-1GROUPNAME0, GROUPNAME1...\s0 )\fR" 4
.IX Item "del_group( GROUPNAME0, GROUPNAME1... )"
This method will delete the list of groups. It has no effect if the 
supplied groups do not exist.
.IP "\fBencpass( \s-1PASSWORD\s0 )\fR" 4
.IX Item "encpass( PASSWORD )"
This method will encrypt plain text into unix style \s-1MD5\s0 password.
.IP "\fBgecos( \s-1USERNAME\s0 [,GECOS] )\fR" 4
.IX Item "gecos( USERNAME [,GECOS] )"
Read or modify a user's \s-1GECOS\s0 string (typically their full name). 
Returns the result of operation (\f(CW1\fR or \f(CW\*(C`undef\*(C'\fR) if \s-1GECOS\s0 was specified. 
Otherwhise returns the \s-1GECOS.\s0
.IP "\fBgid( \s-1USERNAME\s0 [,GID] )\fR" 4
.IX Item "gid( USERNAME [,GID] )"
Read or modify a user's \s-1GID.\s0 Returns the result of operation (\s-1TRUE\s0 or 
\&\s-1FALSE\s0) if \s-1GID\s0 was specified otherwhise returns the \s-1GID.\s0
.IP "\fBhome( \s-1USERNAME\s0 [,HOMEDIR] )\fR" 4
.IX Item "home( USERNAME [,HOMEDIR] )"
Read or modify a user's home directory. Returns the result of operation 
(\f(CW1\fR or \f(CW\*(C`undef\*(C'\fR) if \s-1HOMEDIR\s0 was specified otherwhise returns the \s-1HOMEDIR.\s0
.IP "\fBmaxuid( )\fR" 4
.IX Item "maxuid( )"
This method returns the maximum \s-1UID\s0 in use by all users.
.IP "\fBmaxgid( )\fR" 4
.IX Item "maxgid( )"
This method returns the maximum \s-1GID\s0 in use by all groups.
.IP "\fBunused_uid( [\s-1MINUID\s0] [,MAXUID] )\fR" 4
.IX Item "unused_uid( [MINUID] [,MAXUID] )"
This method returns the first unused \s-1UID\s0 in a given range. The default \s-1MINUID\s0 is 0. The default \s-1MAXUID\s0 is maximal integer value (computed from \f(CW$Config{ intsize }\fR ).
.IP "\fBunused_gid( [\s-1MINGID\s0] [,MAXGID] )\fR" 4
.IX Item "unused_gid( [MINGID] [,MAXGID] )"
This method returns the first unused \s-1GID\s0 in a given range. The default \s-1MINGID\s0 is 0. The default \s-1MAXGID\s0 is maximal integer value (computed from \f(CW$Config{ intsize }\fR ).
.IP "\fBpasswd( \s-1USERNAME\s0 [,PASSWD] )\fR" 4
.IX Item "passwd( USERNAME [,PASSWD] )"
Read or modify a user's password. If you have a plaintext password, 
use the encpass method to encrypt it before passing it to this method. 
Returns the result of operation (\f(CW1\fR or \f(CW\*(C`undef\*(C'\fR) if \s-1PASSWD\s0 was specified. 
Otherwhise returns the \s-1PASSWD.\s0
.IP "\fBrename( \s-1OLDNAME, NEWNAME\s0 )\fR" 4
.IX Item "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 \s-1FALSE\s0 on 
failure and \s-1TRUE\s0 on success.
.IP "\fBshell( \s-1USERNAME\s0 [,SHELL] )\fR" 4
.IX Item "shell( USERNAME [,SHELL] )"
Read or modify a user's shell. Returns the result of operation (\s-1TRUE\s0 
or \s-1FALSE\s0) if \s-1SHELL\s0 was specified otherwhise returns the \s-1SHELL.\s0
.IP "\fBuid( \s-1USERNAME\s0 [,UID] )\fR" 4
.IX Item "uid( USERNAME [,UID] )"
Read or modify a user's \s-1UID.\s0 Returns the result of operation (\s-1TRUE\s0 or 
\&\s-1FALSE\s0) if \s-1UID\s0 was specified otherwhise returns the \s-1UID.\s0
.IP "\fBuser( \s-1USERNAME\s0 [,PASSWD, \s-1UID, GID, GECOS, HOMEDIR, SHELL\s0] )\fR" 4
.IX Item "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.
.IP "\fBgroup( \s-1GROUPNAME\s0 [,GID, \s-1ARRAYREF\s0] )\fR" 4
.IX Item "group( GROUPNAME [,GID, ARRAYREF] )"
This method can add, modify, or return information about a group. 
Supplied with a single groupname parameter, it will return a two element 
list consisting of (\s-1GID, ARRAYREF\s0), where \s-1ARRAYREF\s0 is a ref to array 
consisting names of users in this \s-1GROUP.\s0 It will return undef and ref to empty array (\f(CW\*(C`undef, [ ]\*(C'\fR) if no such group 
exists. If you supply all three parameters, the named group will be 
created or modified if it already exists.
.IP "\fB\fBusers()\fB\fR" 4
.IX Item "users()"
This method returns a list of all existing usernames.
.IP "\fB\fBusers_from_shadow()\fB\fR" 4
.IX Item "users_from_shadow()"
This method returns a list of all existing usernames in a shadow file.
.IP "\fB\fBgroups()\fB\fR" 4
.IX Item "groups()"
This method returns a list of all existing groups.
.IP "\fB\fBgroups_from_gshadow()\fB\fR" 4
.IX Item "groups_from_gshadow()"
This method returns a list of all existing groups in a gshadow file.
.IP "\fBexists_user(\s-1USERNAME\s0)\fR" 4
.IX Item "exists_user(USERNAME)"
This method checks if specified user exists. It returns \s-1TRUE\s0 or \s-1FALSE.\s0
.IP "\fBexists_group(\s-1GROUPNAME\s0)\fR" 4
.IX Item "exists_group(GROUPNAME)"
This method checks if specified group exists. It returns \s-1TRUE\s0 or \s-1FALSE.\s0
.IP "\fBdefault_umask([\s-1UMASK\s0])\fR" 4
.IX Item "default_umask([UMASK])"
This method, if called with an argument, sets default umask for this module (not Your program!).
Otherwise returns the current \s-1UMASK.\s0 Probably You don't want to change this.
.IP "\fBpasswd_file([\s-1PATH\s0])\fR" 4
.IX Item "passwd_file([PATH])"
This method, if called with an argument, sets path to the \fIpasswd\fR file.
Otherwise returns the current \s-1PATH.\s0
.IP "\fBshadow_file([\s-1PATH\s0])\fR" 4
.IX Item "shadow_file([PATH])"
This method, if called with an argument, sets path to the \fIshadow\fR file.
Otherwise returns the current \s-1PATH.\s0
.IP "\fBgroup_file([\s-1PATH\s0])\fR" 4
.IX Item "group_file([PATH])"
This method, if called with an argument, sets path to the \fIgroup\fR file.
Otherwise returns the current \s-1PATH.\s0
.IP "\fBgshadow_file([\s-1PATH\s0])\fR" 4
.IX Item "gshadow_file([PATH])"
This method, if called with an argument, sets path to the \fIgshadow\fR file.
Otherwise returns the current \s-1PATH.\s0
.IP "\fB\fBreset()\fB\fR" 4
.IX Item "reset()"
This method sets paths to files \fIpasswd\fR, \fIshadow\fR, \fIgroup\fR to the
default values.
.IP "\fB\fBerror()\fB\fR" 4
.IX Item "error()"
This method returns the last error (even if \*(L"warnings\*(R" is disabled).
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "Struct::Compare" 4
.IX Item "Struct::Compare"
.PD 0
.IP "Crypt::PasswdMD5" 4
.IX Item "Crypt::PasswdMD5"
.PD
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None known.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
None. I hope.
.SH "THANKS"
.IX Header "THANKS"
.IP "Thanks to Christian Kuelker for suggestions and reporting some bugs :\-)." 4
.IX Item "Thanks to Christian Kuelker for suggestions and reporting some bugs :-)."
.PD 0
.IP "Thanks to Steven Haryanto for suggestions." 4
.IX Item "Thanks to Steven Haryanto for suggestions."
.IP "Thanks to Jonas Genannt for suggestions as well as supplying relevant patch!" 4
.IX Item "Thanks to Jonas Genannt for suggestions as well as supplying relevant patch!"
.IP "\s-1BIG THANKS\s0 to Lopes Victor for reporting some bugs and his exact sugesstions :\-)" 4
.IX Item "BIG THANKS to Lopes Victor for reporting some bugs and his exact sugesstions :-)"
.IP "Thanks to Foudil BRÉTEL for some remarks, suggestions as well as supplying relevant patch!" 4
.IX Item "Thanks to Foudil BRÉTEL for some remarks, suggestions as well as supplying relevant patch!"
.IP "\s-1BIG\s0 thanks to Artem Russakovskii for reporting a bug." 4
.IX Item "BIG thanks to Artem Russakovskii for reporting a bug."
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
Strzelecki Lukasz <lukasz@strzeleccy.eu>
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
.PP
See http://www.perl.com/perl/misc/Artistic.html