SYNOPSIS

     use Unix::Passwd::File;
    
     # list users. by default uses files in /etc (/etc/passwd, /etc/shadow, et al)
     my $res = list_users(); # [200, "OK", ["root", ...]]
    
     # change location of files, return details
     $res = list_users(etc_dir=>"/some/path", detail=>1);
         # [200, "OK", [{user=>"root", uid=>0, ...}, ...]]
    
     # also return detail, but return array entries instead of hash
     $res = list_users(detail=>1, with_field_names=>0);
         # [200, "OK", [["root", "x", 0, ...], ...]]
    
     # get user/group information
     $res = get_group(user=>"paijo"); # [200, "OK", {user=>"paijo", uid=>501, ...}]
     $res = get_user(user=>"titin");  # [404, "Not found"]
    
     # check whether user/group exists
     say user_exists(user=>"paijo");   # 1
     say group_exists(group=>"titin"); # 0
    
     # get all groups that user is member of
     $res = get_user_groups(user=>"paijo"); # [200, "OK", ["paijo", "satpam"]]
    
     # check whether user is member of a group
     $res = is_member(user=>"paijo", group=>"satpam"); # 1
    
     # adding user/group, by default adding user will also add a group with the same
     # name
     $res = add_user (user =>"ujang", ...); # [200, "OK", {uid=>540, gid=>541}]
     $res = add_group(group=>"ujang", ...); # [412, "Group already exists"]
    
     # modify user/group
     $res = modify_user(user=>"ujang", home=>"/newhome/ujang"); # [200, "OK"]
     $res = modify_group(group=>"titin"); # [404, "Not found"]
    
     # deleting user will also delete user's group
     $res = delete_user(user=>"titin");
    
     # change user password
     $res = set_user_password(user=>"ujang", pass=>"foobar");
     $res = modify_user(user=>"ujang", pass=>"foobar"); # same thing
    
     # add/delete user to/from group
     $res = add_user_to_group(user=>"ujang", group=>"wheel");
     $res = delete_user_from_group(user=>"ujang", group=>"wheel");
    
     # others
     $res = get_max_uid(); # [200, "OK", 65535]
     $res = get_max_gid(); # [200, "OK", 65534]

DESCRIPTION

    This module can be used to read and manipulate entries in Unix system
    password files (/etc/passwd, /etc/group, /etc/group, /etc/gshadow; but
    can also be told to search in custom location, for testing purposes).

    This module uses a procedural (non-OO) interface. Each function in this
    module open and read the passwd files once. Read-only functions like
    `list_users()` and `get_max_gid()` open in read-only mode. Functions
    that might write to the files like `add_user()` or `delete_group()`
    first lock `passwd.lock` file, open in read+write mode and also read
    the files in the first pass, then seek to the beginning and write back
    the files.

    No caching is done so you should do your own if you need to.

SEE ALSO

    Old modules on CPAN which do not support shadow files are pretty
    useless to me (e.g. Unix::ConfigFile). Shadow passwords have been
    around since 1988 (and in Linux since 1992), FFS!

    Passwd::Unix. I created a fork of Passwd::Unix v0.52 called
    Passwd::Unix::Alt in 2011 to fix some of the deficiencies/quirks in
    Passwd::Unix, including: lack of tests, insistence of running as root
    (despite allowing custom passwd files), use of not-so-ubiquitous bzip2,
    etc. Then in 2012 I decided to create Unix::Passwd::File. Here are how
    Unix::Passwd::File differs compared to Passwd::Unix (and
    Passwd::Unix::Alt):

      * tests in distribution

      * no need to run as root

      * no need to be able to read the shadow file for some operations

      For example, list_users() will simply not return the encpass field if
      the shadow file is unreadable. Of course, access to shadow file is
      required when getting or setting password.

      * strictly procedural (non-OO) interface

      I consider this a feature :-)

      * detailed error message for each operation

      * removal of global error variable

      * working locking

      Locking is done by locking passwd.lock file.

    Setup::Unix::User and Setup::Unix::Group, which use this module.

    Rinci