NAME

       Unix::GroupFile - Perl interface to /etc/group format files

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.

AUTHOR

       Steve Snodgrass, ssnodgra@fore.com

SEE ALSO

       Unix::AliasFile, Unix::AutomountFile, Unix::ConfigFile, Unix::PasswdFile