SYNOPSIS
use Unix::GroupFile;
$grp = new Unix::GroupFile "/etc/group";
$grp->group("bozos", "*", $grp->maxgid + 1, @members);
$grp->remove_user("coolgrp", "bgates", "badguy");
$grp->add_user("coolgrp", "joecool", "goodguy");
$grp->remove_user("*", "deadguy");
$grp->passwd("bozos", $grp->encpass("newpass"));
$grp->commit();
undef $grp;
DESCRIPTION
The Unix::GroupFile module provides an abstract interface to /etc/group format
files. It automatically handles file locking, getting colons and commas in
the right places, and all the other niggling details.
This module also handles the annoying problem (at least on some systems) of
trying to create a group line longer than 512 characters. Typically this is
done by creating multiple lines of groups with the same GID. When a new
GroupFile object is created, all members of groups with the same GID are
merged into a single group with a name corresponding to the first name found
in the file for that GID. When the file is committed, long groups are written
out as multiple lines of no more than 512 characters, with numbers appended to
the group name for the extra lines.
METHODS
add_user( GROUP, @USERS )
This method will add the list of users to an existing group. Users that are
already members of the group are silently ignored. The special group name *
will add the users to every group. Returns 1 on success or 0 on failure.
commit( [BACKUPEXT] )
See the Unix::ConfigFile documentation for a description of this method.
delete( GROUP )
This method will delete the named group. It has no effect if the supplied
group does not exist.
encpass( PASSWORD )
See the Unix::ConfigFile documentation for a description of this method.
gid( GROUP [,GID] )
Read or modify a group's GID. Returns the GID in either case. Note that it
is illegal to change a group's GID to a GID that is already in use by another
group. In this case, the method returns undef.
group( GROUP [,PASSWD, GID, @USERS] )
This method can add, modify, or return information about a group. Supplied
with a single group parameter, it will return a list consisting of (PASSWORD,
GID, @MEMBERS), or undef if no such group exists. If you supply at least
three parameters, the named group will be created or modified if it already
exists. The list is also returned to you in this case. Note that it is
illegal to specify a GID that is already in use by another group. In this
case, the method returns undef.
groups( [SORTBY] )
This method returns a list of all existing groups. By default the list will
be sorted in order of the GIDs of the groups. You may also supply ``name'' as a
parameter to the method to get the list sorted by group name. In scalar
context, this method returns the total number of groups.
maxgid( )
This method returns the maximum GID in use by all groups.
members( GROUP [,@USERS] )
Read or modify the list of members associated with a group. If you specify
any users when you call the method, all existing members of the group are
removed and your list becomes the new set of members. In scalar context,
this method returns the total number of members in the group.
new( FILENAME [,OPTIONS] )
See the Unix::ConfigFile documentation for a description of this method.
passwd( GROUP [,PASSWD] )
Read or modify a group'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.
remove_user( GROUP, @USERS )
This method will remove the list of users from an existing group. Users that
are not members of the group are silently ignored. The special group name *
will remove the users from every group. Returns 1 on success or 0 on failure.
rename_user( OLDNAME, NEWNAME )
This method will change one username to another in every group. Returns the
number of groups affected.
