Unix::PasswdFile - Perl interface to /etc/passwd format files

  use Unix::PasswdFile;

  $pw = new Unix::PasswdFile "/etc/passwd";
  $pw->user("joeblow", $pw->encpass("secret"), $pw->maxuid + 1, 10,
	    "Joe Blow", "/export/home/joeblow", "/bin/ksh");
  $pw->delete("deadguy");
  $pw->passwd("johndoe", $pw->encpass("newpass"));
  foreach $user ($pw->users) {
      print "Username: $user, Full Name: ", $pw->gecos($user), "\n";
  }
  $pw->commit();
  undef $pw;

package Unix::PasswdFile;

# $Id: PasswdFile.pm,v 1.5 2000/05/02 15:58:36 ssnodgra Exp $

use strict;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
use Unix::ConfigFile;

require Exporter;

@ISA = qw(Unix::ConfigFile Exporter);
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw(
	
);
$VERSION = '0.06';

# Implementation notes
#
# This module only adds a single field to the basic ConfigFile object.
# The field is called 'pwent' (password entry) and is a hash of arrays
# (or, more properly, a reference to a hash of references to arrays!).
# The key is the username and the array contents are the next six fields
# found in the password file.

# Preloaded methods go here.

# Read the file and build the data structures
sub read {
    my ($this, $fh) = @_;

    while (<$fh>) {
	chop;
	$this->user(split /:/);
    }
    return 1;
}


# Add or change a user
sub user {
    my $this = shift;

    my $username = shift;
    unless (@_) {
	return undef unless defined $this->{pwent}{$username};
	return @{$this->{pwent}{$username}};
    }
    return undef if @_ > 6;
    # Need to pad the list to 6 elements or we might lose colons during commit
    push @_, "" while @_ < 6;
    # Note: I first tried setting this to \@_.  Bad idea!
    $this->{pwent}{$username} = [ @_ ];
}


# Rename a user
sub rename {
    my ($this, $olduser, $newuser) = @_;

    return 0 unless defined $this->user($olduser);
    $this->user($newuser, $this->user($olduser));
    $this->delete($olduser);
    return 1;
}


# Delete a user
sub delete {
    my ($this, $username) = @_;
    delete $this->{pwent}{$username};
}


# Return the list of usernames
# Accepts a sorting order parameter: uid or name (default uid)
sub users {
    my $this = shift;
    my $order = @_ ? shift : "uid";

    # Is there a way to make this work right in scalar context without
    # this check?  I couldn't find one.
    return keys %{$this->{pwent}} unless wantarray;
    if ($order eq "name") {
	sort keys %{$this->{pwent}};
    }
    else {
	sort { $this->uid($a) <=> $this->uid($b) } keys %{$this->{pwent}};
    }
}


# Returns the maximum UID in use in the file
sub maxuid {
    my ($this, $ignore) = @_;
    my @uids = sort { $a <=> $b } map { $this->{pwent}{$_}[1] } keys %{$this->{pwent}};
    return undef unless @uids;
    my $retval = pop @uids;
    if (defined $ignore) {
	while ($retval >= $ignore && @uids) {
	    $retval = pop @uids;
	}
    }
    return $retval;
}


# Output the file to disk
sub write {
    my ($this, $fh) = @_;

    # Make sure to output root first if it exists
    if (defined $this->user("root")) {
	print $fh join(":", "root", $this->user("root")), "\n" or return 0;
    }
    foreach my $user ($this->users) {
	next if ($user eq "root");
	print $fh join(":", $user, $this->user($user)), "\n" or return 0;
    }
    return 1;
}


# Accessors (these all accept a username and an optional value)
# These must check for undefined data, or the act of accessing an array
# element will create the data!!  (This horrible bug nearly escaped into
# the first alpha release.  :-)
sub passwd {
    my $this = shift;
    my $username = shift;
    return undef unless defined $this->{pwent}{$username};
    @_ ? $this->{pwent}{$username}[0] = shift : $this->{pwent}{$username}[0];
}

sub uid {
    my $this = shift;
    my $username = shift;
    return undef unless defined $this->{pwent}{$username};
    @_ ? $this->{pwent}{$username}[1] = shift : $this->{pwent}{$username}[1];
}

sub gid {
    my $this = shift;
    my $username = shift;
    return undef unless defined $this->{pwent}{$username};
    @_ ? $this->{pwent}{$username}[2] = shift : $this->{pwent}{$username}[2];
}

sub gecos {
    my $this = shift;
    my $username = shift;
    return undef unless defined $this->{pwent}{$username};
    @_ ? $this->{pwent}{$username}[3] = shift : $this->{pwent}{$username}[3];
}

sub home {
    my $this = shift;
    my $username = shift;
    return undef unless defined $this->{pwent}{$username};
    @_ ? $this->{pwent}{$username}[4] = shift : $this->{pwent}{$username}[4];
}

sub shell {
    my $this = shift;
    my $username = shift;
    return undef unless defined $this->{pwent}{$username};
    @_ ? $this->{pwent}{$username}[5] = shift : $this->{pwent}{$username}[5];
}


# Autoload methods go after =cut, and are processed by the autosplit program.

1;
__END__
# Below is the stub of documentation for your module. You better edit it!