plucky (3) Unix::GroupFile.3pm.gz

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