LCFG::Utils::GroupFile - Read and Write Unix group files
This documentation refers to LCFG::Utils::GroupFile version 1.2.1
use LCFG::Utils::GroupFile;
my $group = LCFG::Utils::GroupFile->new_from_file();
my @groups = $group->list_groups;
my @gids = $group->list_gids;
my @entries = $group->list_entries;
# Add/Delete/Update entries
my $daemon = $group->get_entry_for_name("daemon");
$daemon->members("root,bin,daemon");
$group->remove_entry_for_name('fred');
$group->to_file;This module provides an object-oriented interface to the Unix group file. It can parse a group file and then provide lists of GIDs and group names. There is support for adding, removing and updating entries. Support is also provided for finding the differences between two different group files.
This is a reference to a hash which maps the GID to the associated group file entry. Normally it is better to find group entries by using the get_entry_for_gid and has_entry_for_gid methods. Do not add and remove entries directly from this hash use the add_entry and remove_entry_for_gid methods.
This is a reference to a hash which maps the group name to the associated group file entry. Normally it is better to find group entries by using the get_entry_for_name and has_entry_for_name methods. Do not add and remove entries directly from this hash use the add_entry and remove_entry_for_name methods.
The following class methods are available.
This will create a new, empty, LCFG::Utils::GroupFile object to which entries can be added.
This method will create a new LCFG::Utils::GroupFile object based on the contents of the specified Unix group file. If no file name is given then the default, /etc/group, will be parsed.
The add_entry method is used to add an entry for each line. If multiple identical lines are found the later ones will be ignored. If entries with the same GID and group name but with other fields differing are found then the later entry wins. Otherwise, if multiple entries are found for a GID with different names or multiple entries are found for a name with different GIDs this method will die.
The following methods can be called on an LCFG::Utils::GroupFile object.
This will write all the group file entries stored in the LCFG::Utils::GroupFile object into the specified file. If no file name is given then the default, /etc/group, will be used, note that, typically, root access will be required to write to that file. The entries will be written out in numerical GID order.
This takes a second LCFG::Utils::GroupFile object and returns references to 3 lists. The first is the list of entries which are only in this object, the second is the list of entries which are only in the other object, the third is the list of entries which appear in both but have some differences. For example:
my $group1 = LCFG::Utils::GroupFile->new_from_file("/etc/group");
my $group2 = LCFG::Utils::GroupFile->new_from_file("/etc/group.new");
my ( $missing, $extras, $diffs ) = $group1->diff($group2);Each item in the missing and extras lists is an LCFG::Utils::GroupFile::Entry object. Each item in the diffs list is an array-reference to a pair of LCFG::Utils::GroupFile::Entry objects, the first entry is from this group object, the second entry is from the other group object.
All three lists are sorted numerically on the GID.
This returns the list of entries (i.e. LCFG::Utils::GroupFile::Entry objects) in the group file. The returned list will be sorted according to the GID field.
This returns the list of GIDs in this group file. The returned list will be sorted numerically.
This returns the list of group names in this group file. The returned list will be sorted alphabetically.
This method returns a boolean which signifies whether or not the GID is currently used in the group file.
This method will return the LCFG::Utils::GroupFile::Entry object associated with the specified GID. If no entry is found for the specified GID then this method will die.
This method returns a boolean which signifies whether or not the username is currently used in the group file.
This method will return the LCFG::Utils::GroupFile::Entry object associated with the specified username. If no entry is found for the specified username then this method will die.
This method will add an LCFG::Utils::GroupFile::Entry object to the list of entries for the group file. It can take a string with the fields delimited using the standard colon (:), or a reference to a hash of the fields required to create an LCFG::Utils::GroupFile::Entry object, or a previously assembled LCFG::Utils::GroupFile::Entry object.
If multiple identical lines are found the later ones will be ignored. If entries with the same GID and username but with other fields differing are found then the later entry wins. Otherwise, if multiple entries are found for a GID with different usernames or multiple entries are found for a username with different GIDs this method will die.
This takes an LCFG::Utils::GroupFile::Entry object and removes a matching entry from the stored list of entries for the group file. If the entry is not currently stored then this error does not fail. If incompatible entries are found for the GID or username then this method will fail.
This method will remove the entry associated with the specified GID. Internally it uses the get_entry_for_gid method so if there is no entry for this GID the method will fail. If this is a problem then check for existence first using the has_entry_for_gid method.
This method will remove the entry associated with the specified username. Internally it uses the get_entry_for_name method so if there is no entry for this username the method will fail. If this is a problem then check for existence first using the has_entry_for_name method.
This module requires List::MoreUtils, Readonly and Try::Tiny.
LCFG::Utils::GroupFile::Entry, LCFG::Utils::PasswdFile, LCFG::Utils::PasswdFile::Entry, LCFG::Component::Auth
This is the list of platforms on which we have tested this software. We expect this software to work on any Unix-like platform which is supported by Perl.
Scientific5, Scientific6, Fedora13
Please report any bugs or problems (or praise!) to bugs@lcfg.org, feedback and patches are also always very welcome.
Alastair Scobie <ascobie@inf.ed.ac.uk>, Stephen Quinney <squinney@inf.ed.ac.uk>Copyright (C) 2011 University of Edinburgh. All rights reserved.This library is free software; you can redistribute it and/or modify it under the terms of the GPL, version 2 or later.