Provided by: libpasswd-unix-perl_1.09-1_all 
NAME
Passwd::Unix - access to standard unix files
SYNOPSIS
use Passwd::Unix;
my $pu = Passwd::Unix->new;
my $err = $pu->user(
"example",
$pu->encpass("my_secret"),
$pu->unused_uid,
$pu->unused_gid,
"My User",
"/home/example",
"/bin/bash"
);
$pu->passwd("example", $pu->encpass( "newsecret") );
foreach my $user ($pu->users) {
print "Username: $user\nFull Name: ", $pu->gecos($user), "\n\n";
}
my $uid = $pu->uid('example');
$pu->del("example");
# or
use Passwd::Unix qw(
algorithm backup check_sanity compress del del_group del_user
encpass exists_group exists_user gecos gid group group_file
groups groups_from_gshadow home maxgid maxuid mingid minuid
passwd passwd_file rename reset shadow_file shell uid user
users users_from_shadow warnings
);
my $err = user( "example", encpass("my_secret"), unused_uid(), unused_gid(),
"My User", "/home/example", "/bin/bash" );
passwd("example",encpass("newsecret"));
foreach my $user ( users() ) {
print "Username: $user\nFull Name: ", gecos( $user ), "\n\n";
}
my $uid = uid( 'example' );
del( 'example' );
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 for testing software
without using system critical files in /etc/ dir (you can specify other files than /etc/passwd etc.).
DESCRIPTION
The Passwd::Unix module provides an abstract interface to /etc/passwd, /etc/shadow, /etc/group,
/etc/gshadow format files. It is inspired by Unix::PasswdFile module (that one does not handle
/etc/shadow file).
Module was rewritten from the ground in version 1.0 (i.e. to support newer hash algorithms and so on),
however with compatibility in mind. Despite this some incompatibilities can occur.
SUBROUTINES/METHODS
new( [ param0 = 1, param1 => 0... ] )>
Constructor. Possible parameters are:
passwd - path to passwd file; default "/etc/passwd"
shadow - path to shadow file; default "/etc/shadow"
group - path to group file; default "/etc/group"
gshadow - path to gshadow file if any; default "/etc/gshadow"
algorithm - hash algorithm, possible values: md5, blowfish, sha256, sha512; default "sha512"
umask - not used anymore; left only for compatibility reason
debug - not used anymore; left only for compatibility reason
backup - boolean; if set to 1, backup will be made; default 1
compress - boolean; if set to 1, backup compression will be made; default 1
warnings - boolean; if set to 1, important warnings will be displayed; default 0
algorithm()
This method allows to specify algorithm for password generation. Possible values: "md5", "blowfish",
"sha256", "sha512"
backup()
This method allows to specify if backups files have to be made before every modyfication (1 for on, 0
for off).
compress()
This method allows to specify if compression to backup files has to be made (1 for on, 0 for off).
check_sanity()
This function was left only for compatibility reason. Currently it does nothing (always returns 1).
debug()
This function was left only for compatibility reason. Currently it does nothing.
default_umask( [UMASK] )
This function was left only for compatibility reason. Currently it does nothing.
del( USERNAME0, USERNAME1... )
This method is an alias for "del_user". It's for transition only.
del_user( USERNAME0, USERNAME1... )
This method will delete the list of users. It has no effect if the supplied users do not exist.
del_group( GROUPNAME0, GROUPNAME1... )
This method will delete the list of groups. It has no effect if the supplied groups do not exist.
encpass( PASSWORD )
This method will encrypt plain text into unix style password.
error()
This method returns the last error (even if "warnings" is disabled).
exists_user(USERNAME)
This method checks if specified user exists. It returns "undef" on failure and 1 on success.
exists_group(GROUPNAME)
This method checks if specified group exists. It returns "undef" on failure and 1 on success.
gecos( USERNAME [,GECOS] )
Read or modify a user's GECOS string (typically full name). Returns the result of operation (1 or
"undef") if GECOS was specified. Otherwhise returns the GECOS if any.
gid( USERNAME [,GID] )
Read or modify a user's GID. Returns the result of operation (1 or "undef") if GID was specified
otherwhise returns the GID if any.
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 (GID, ARRAYREF), where ARRAYREF is a ref
to array consisting names of users in this GROUP. It will return undef and ref to empty array
("undef, [ ]") if no such group exists. If you supply all three parameters, the named group will be
created or modified if it already exists.
group_file([PATH])
This method, if called with an argument, sets path to the group file. Otherwise returns the current
PATH.
groups()
This method returns a list of all existing groups.
groups_from_gshadow()
This method returns a list of all existing groups in a gshadow file.
gshadow_file([PATH])
This method, if called with an argument, sets path to the gshadow file. Otherwise returns the
current PATH.
home( USERNAME [,HOMEDIR] )
Read or modify a user's home directory. Returns the result of operation (1 or "undef") if HOMEDIR was
specified otherwhise returns the HOMEDIR if any.
maxuid( )
This method returns the maximum UID in use.
maxgid()
This method returns the maximum GID in use.
minuid( [UID] )
This method returns the minimum UID in use, that is greater then spupplied.
mingid()
This method returns the minimum GID in use, that is greater then spupplied.
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 (1 or "undef") if PASSWD was
specified. Otherwhise returns the PASSWD if any.
passwd_file([PATH])
This method, if called with an argument, sets path to the passwd file. Otherwise returns the current
PATH.
rename( OLDNAME, NEWNAME )
This method changes the username for a user. If NEWNAME corresponds to an existing user, that user
will be overwritten. It returns "undef" on failure and 1 on success.
reset()
This method sets paths to files passwd, shadow, group, gshadow to the default values.
shell( USERNAME [,SHELL] )
Read or modify a user's shell. Returns the result of operation (1 or "undef") if SHELL was specified
otherwhise returns the SHELL if any.
uid( USERNAME [,UID] )
Read or modify a user's UID. Returns the result of operation (1 or "undef") if UID was specified
otherwhise returns the UID if any.
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 (PASSWORD, UID, GID, GECOS, HOMEDIR,
SHELL), 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.
users()
This method returns a list of all existing usernames.
users_from_shadow()
This method returns a list of all existing usernames in a shadow file.
shadow_file([PATH])
This method, if called with an argument, sets path to the shadow file. Otherwise returns the current
PATH.
unused_uid( [MINUID] [,MAXUID] )
This method returns the first unused UID in a given range. The default MINUID is 0. The default
MAXUID is maximal integer value (computed from $Config{ intsize } ).
unused_gid( [MINGID] [,MAXGID] )
This method returns the first unused GID in a given range. The default MINGID is 0. The default
MAXGID is maximal integer value (computed from $Config{ intsize } ).
warnings()
This method allows to specify if warnings has to be displayed (1 for on, 0 for off). Whether you can
check last warning/failure by calling "error".
DEPENDENCIES
Crypt::Password
IO::Compress::Bzip2
Path::Tiny
Tie::Array::CSV
TODO
Preparation of tests.
INCOMPATIBILITIES
None known.
BUGS AND LIMITATIONS
None. I hope.
THANKS
Thanks to Jonas Genannt for many suggestions and patches!
Thanks to Christian Kuelker for suggestions and reporting some bugs :-).
Thanks to Steven Haryanto for suggestions.
BIG THANKS to Lopes Victor for reporting some bugs and his exact sugesstions :-)
Thanks to Foudil BRÉTEL for some remarks, suggestions as well as supplying relevant patch!
BIG thanks to Artem Russakovskii for reporting a bug.
AUTHOR
Strzelecki Lukasz <lukasz@strzeleccy.eu>
LICENCE AND COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.
See http://www.perl.com/perl/misc/Artistic.html
POD ERRORS
Hey! The above document had some coding errors, which are explained below:
Around line 1365:
Non-ASCII character seen before =encoding in 'BRÉTEL'. Assuming UTF-8
perl v5.40.1 2025-11-03 Passwd::Unix(3pm)