NAME

Pquota - a UNIX print quota module

SYNOPSIS

    use Pquota;

    # object creator and destructor
    $pquota = Pquota->new ("/path/to/quota/directory"[, $opts]);
    $pquota->close ();

    # printers database commands
    $pquota->printer_add ($printer, $page_cost, $user_db);
    $pquota->printer_rm ($printer);
    $pquota->printer_set_cost ($printer, $cost);
    $pquota->printer_get_cost ($printer);
    $pquota->printer_get_cost_list ();
    $pquota->printer_set_user_database ($printer, $user_db);
    $pquota->printer_get_user_database ($printer);
    $pquota->printer_get_user_database_list ();
    $pquota->printer_set_field ($printer, $key, $value);
    $pquota->printer_get_field ($printer, $key);

    # user database commands
    $pquota->user_add ($user, $user_db, $periodic_quota);
    $pquota->user_rm ($user, $user_db);
    $pquota->user_print_pages ($user, $printer, $num_pages);
    $pquota->user_add_to_current ($user, $user_db, $amount);
    $pquota->user_set_current ($user, $user_db, $periodic_quota);
    $pquota->user_get_current_by_dbm ($user, $user_db);
    $pquota->user_get_current_by_printer ($user, $printer);
    $pquota->user_reset_current ($user, $user_db);
    $pquota->user_add_to_periodic ($user, $user_db, $amount);
    $pquota->user_set_periodic ($user, $user_db, $amount);
    $pquota->user_get_periodic ($user, $user_db);
    $pquota->user_reset_total ($user, $user_db);
    $pquota->user_set_field ($user, $user_db, $key, $value);
    $pquota->user_get_field ($user, $user_db, $key);

DESCRIPTION

This module is an attempt to provide an easy interface to a group of DBM files used to store print quota information on a UNIX system. It makes writing printer interface scripts a lot easier. Pquota requires the MLDBM module.

As we've said, Pquota is a wrapper module for handling DBM files. We've structured it so that there is one database that contains information about the different printers on your system, and any number of user databases. The printers database, which we've named _printers to (hopefully) avoid any namespace clashes. An entry in the _printers database looks something like this:

        $printer_entry = {'cost'        =>      5,
                          'dbm'         =>      'students'};

Every printer has a cost per page, and an associated user database. Multiple printers can point to the same user database, but you can't have multiple databases for the same printer.

Pquota is designed with a periodic allotment of quota in mind. On our systems, students get a couple dollars worth every week. So every entry in a user database looks like this:

        $user_entry = {'periodic'       =>      300,
                       'current'        =>      273,
                       'total'          =>      27      };

And once a week, we run a cron job to reset all the current values to be equal to the periodic values.

Pquota also has pessimistic file locking internal to its DBM accesses, so there won't be any problems with corrupt DBM files. However, we decided not to register any signal handlers to deal with signals when the files are locked, because we didn't want to be overriding any handlers in the enclosing program. Just in case, all of the lock files are named dbm.lock, where dbm is the name of the DBM that is locked. They reside in the same directory as the DBMs themselves.

MLDBM Notes

MLDBM by default uses Data::Dumper to translate Perl data structures into strings, and SDBM_File to store them to disk. This is because SDBM_File comes with all UNIX installs of Perl, and Data::Dumper was originally the only module which could serialize Perl's data structures. However, it also has the option of using any of the other DBM modules for storage, and either Storable or FreezeThaw to serialize the structures. As such, we've added the $opts option to the new method. Just give it a hash reference, with the keys 'UseDB' or 'Serializer', to set either the DBM module or the serializing module, respectively. For example,

    $pquota = Pquota->new ("/var/spool/pquota", {'UseDB' => 'DB_File'});

would tell MLDBM to use the DB_File module to store the structures to disk.

Also, to avoid unnecessary locking, we've added an option to open the databases in read-only mode, so that scripts that won't be writing to the databases don't lock it. Simply set the 'RO' option to 'true' in order to open the databases in read-only mode.

    $pquota = Pquota->new ("/var/spool/pquota", {'RO' => 'true'});

Method Notes

All methods return either the requested information or 1 in case of success, and undef in case of failure.

Object Methods

Pquota::new ($quotadir[, $opts]): Standard object constructor. $quotadir should contain the path to a directory to store the DBMs. The optional $opts should be a reference to a hash, as described in MLDBM Notes.
Pquota::close (): Closes all open databases. The database methods will open the DBMs as needed, but you must call Pquota::close() before exiting your program in order to make sure the DBMs are properly closed.

Printer Database Methods

Pquota::printer_add ($printer, $page_cost, $user_db): Adds a printer to the printers DBM, with the associated per-page cost and user database.
Pquota::printer_rm ($printer): Removes a printer from the printers DBM.
Pquota::printer_set_cost ($printer, $cost): Sets the per-page cost for the printer.
Pquota::printer_get_cost ($printer): Returns the per-page cost for the printer.
Pquota::printer_get_cost_list (): Returns a reference to a hash, with printer names as keys, and their per-page costs as the values.
Pquota::printer_set_user_database ($printer, $user_db): Sets the printer's associated user database.
Pquota::printer_get_user_database ($printer): Returns the name of the printer's associated user database.
Pquota::printer_get_user_database_list (): Returns a reference to a hash, with printer names as keys, and their per-page costs as the values.
Pquota::printer_set_field ($printer, $key, $value): Sets an arbitrary field in the printer's record. This is in case you want to store more information about your printers than Pquota supports natively.
Pquota::printer_get_field ($printer, $key);: Returns the value store in an arbitrary field in the printer's record.

User Database Methods

Pquota::user_add ($user, $user_db, $periodic_quota): Adds an entry to a user database, with the indicated periodic quouta.
Pquota::user_rm ($user, $user_db): Removes a user from the specified user database.
Pquota::user_print_pages ($user, $printer, $num_pages): Modifies the user database to reflect the fact that the user has printed the indicated number of pages on the specified printer.
Pquota::user_add_to_current ($user, $user_db, $amount): Adds the specified amount to the user's current remaining quota.
Pquota::user_set_current ($user, $user_db. $amount): Sets the user's current remaining quota.
Pquota::user_get_current_by_dbm ($user, $user_db): Returns the user's current remaining quota.
Pquota::user_get_current_by_printer ($user, $printer): Returns the user's current remaining quota in the user database associated with that printer.
Pquota::user_reset_current ($user, $user_db): Resets the user's current remaining quota to his periodic quota value.
Pquota::user_add_to_periodic ($user, $user_db, $amount): Adds the specified amount to the user's periodic quota allotment.
Pquota::user_set_periodic ($user, $user_db, $amount): Sets the user's periodic quota allotment.
Pquota::user_get_periodic ($user, $user_db): Returns the user's periodic quota allotment.
Pquota::user_reset_total: Sets the user's total quota used to 0.
Pquota::user_set_field ($user, $user_db, $key, $value): Sets an arbitrary field in the user's record.
Pquota::user_get_field ($user, $user_db, $key): Returns the value stored in an arbitrary field in the user's record.

TO DO

Come up with more functionality. Pquota currently does everything we need, but we're sure there must be features it lacks.

BUGS

None that we know of. Please feel free to mail us with any bugs, patches, suggestions, comments, flames, death threats, etc.

AUTHORS

David Bonner <dbonner@cs.bu.edu> and Scott Savarese <savarese@cs.bu.edu>

VERSION

Version 1.00 April 30, 1999

COPYRIGHT

To install Pquota, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Pquota

CPAN shell

perl -MCPAN -e shell
install Pquota

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)