RATS file locking

        Currently RATS only performs locks on four files: password, shadow,
        group and reserve. The locking consists in creating a lock file
        defined in rats.conf AND doing an flock on that file. This is
        abstracted away in the RatsLib.pm library in two functions,
        "lock_file()" and "unlock_file()" which take as arguments the
        name tokens of the files as defined in rats.conf. However note that
        locking is not distributed across clusters and you will always lock
        the file on the machine you are performing the lock on.

        For example your rats.conf main contain:

        LOCK_FILE = (
               'group'  => '/etc/gtmp',
               'passwd' =>'/etc/ptmp',
               'shadow' =>'/etc/stmp',
               'reserve'=> '/usr/local/accounts/etc/rtmp',
               );
 

        You could call

        $response = &RatsLib::lock_file('passwd');

        You should check the return value, which would tell you if
        the lock succeeded. The return value for lock_files is a
        configurable string indicating success, or failure and
        cause. Here is an example of the checking code:

        unless ($response eq $CONFIG::RESPONSE{'SCS'}) {
                print "Failed to get lock: $response\n";
         }

        The only succefull return is that given by $CONFIG::RESPONSE{'SCS'}
        all other returns are informative messages about the cause of the
        lock failure.

        To unlock the file simply call

        &RatsLib::unlock_file('passwd');

        The return value of this is meaningless because it is hard to
        tell if if a flock release failed.

        So here is a bit of code illustrating the above:

        #/usr/local/bin/perl
        require "/usr/local/accounts/etc/rats_internal.conf";
        require "/usr/local/accounts/lib/RatsLib.pm";

        $response = &RatsLib::lock_file('passwd');
        unless ($response eq $CONFIG::RESPONSE{'SCS'}) {
                die("Failed to get lock: $response\n");
 
         }
 
        # do the actual work
        &do_some_password_hack;
 
        &RatsLib::unlock_file('passwd');
 
        print "Yey! It worked!\n";
        exit;