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.

AUTHOR

Steve Snodgrass, ssnodgra@fore.com