Quota/README  v1.0  Aug/97  tnzoerne

Quota extension module for Perl
-------------------------------

Author:   Tom Zoerner
          IMMD4, CSD, University of Erlangen-Nuernberg
          Tom.Zoerner@informatik.uni-erlangen.de

Version:   1.0
Date:      Aug/28/1997
DSLI-code: Rdcf
           - stable release
	   - support by developer
	   - C compiler required for installation
	   - plain functions, no references used
Supported: SunOS 4.1.3,
	   Solaris 2.4 & 2.5,
           HP-UX 9.0x & 10.10 & 10.20,
	   IRIX 5.2 & 5.3 & 6.2,
           OSF/1,
	   BSDI 2 (no RPC),
	   Linux prepared
Location:  http://www.perl.com/CPAN/authors/Tom_Zoerner/
Author:    TOMZO  Tom Zoerner <Tom.Zoerner@informatik.uni-erlangen.de>
Copyright: none / Public Domain

Documentation is in pod format at the end of Quota.pm,
installation hints are in a file named INSTALL inside this package.

-----------------------------------------------------------------------------
  THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
  IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
-----------------------------------------------------------------------------

NAME
    Quota - Perl interface to file system quotas

SYNOPSIS
        use Quota;

        ($block_curr, $block_soft, $block_hard, $block_timelimit,
         $inode_curr, $inode_soft, $inode_hard, $inode_timelimit) =
        Quota::query($dev [,$uid]);

        ($block_curr, $block_soft, $block_hard, $block_timelimit,
         $inode_curr, $inode_soft, $inode_hard, $inode_timelimit) =
        Quota::rpcquery($host, $path [,$uid]);

        Quota::setqlim($dev, $uid, $block_soft, $block_hard,
                       $inode_soft, $inode_hard [,$tlo]);

        Quota::sync([$dev]);

        $arg = Quota::getqcarg([$path]);

        Quota::setmntent();
        ($dev, $path, $type, $opts) = Quota::getmntent();
        Quota::endmntent();


DESCRIPTION
    The Quota module provides access to file system quotas. The quotactl
    system call or ioctl is used to query or set quotas on the local host,
    or queries are submitted via RPC to a remote host. Mount tables can be
    parsed with getmntent and paths can be translated to device files (or
    whatever the actual quotactl implementations needs as argument) of the
    according file system.

  Functions

     ($bc,$bs,$bh,$bt, $ic,$is,$ih,$it) = Quota::query($dev, $uid)
        Get current usage and quota limits for a given file system and user.
        The user is specified by its numeric uid; defaults to the process'
        real uid.

        The type of $dev varies from system to system. It's the argument
        which is used by the quotactl implementation to address a specific
        file system. It may be the path of a device file (e.g. /dev/sd0a) or
        the path of the mount point or the quotas file at the top of the
        file system (e.g. /home.stand/quotas). However you do not have to
        worry about that; use Quota::getqcarg to automatically translate any
        path inside a file system to the required $dev argument.

        $dev may also be in the form of hostname:path, which has the
        module transparently query the given host via a remote procedure
        call (RPC). In case you have NFS (or similar network mounts), this
        type of argument may also be produced by Quota::getqcarg. Note: RPC
        queries require rquotad(1m) to be running on the target system. If
        the daemon or host are down, the timeout is 12 seconds.

        In $bc and $ic the current usage in blocks and inodes is
        returned. $bs and $is are the soft limits, $bh and $ih hard
        limits. If the soft limit is exceeded, writes by this user will fail
        for blocks or inodes after $bt or $it is reached. These times
        are expressed as usual, i.e. in elapsed seconds since 00:00
        1/Jan/1970 GMT.

     Quota::setqlim($dev, $uid, $bs,$bh, $is,$ih, $tlo)
        Sets quota limits for the given user. Meanings of $dev, $uid,
        $bs, $bh, $is and $ih are the same as in Quota::query.

        $tlo decides how the time limits are initialized: 0: The time
        limits are set to NOT STARTED, i.e. the time limits are not
        initialized until the first write attempt by this user. This is the
        default. 1: The time limits are set to 7.0 days. More alternatives
        (i.e. setting a specific time) aren't available in most
        implementations.

        Note: if you want to set the quota of a particular user to zero,
        i.e. no write permission, you must not set all limits to zero, since
        that is equivalent to unlimited access. Instead set only the hard
        limit to 0 and the soft limit for example to 1.

        Note that you cannot set quotas via RPC.

     Quota::sync($dev)
        Have the kernel update the quota file on disk or all quota files if
        no argument given (the latter doesn't work on all systems, in
        particular on HP-UX 10.10).

        The main purpose of this function is to check if quota is enabled in
        the kernel and for a particular file system. Read the quotaon(1m)
        man page on how to enable quotas on a file system.

     ($bc,$bs,$bh,$bt, $ic,$is,$ih,$it) =
        Quota::rpcquery($host,$path,$uid)

        This is equivalent to Quota::query("$host:$path",$uid), i.e. query
        quota for a given user on a given remote host via RPC. $path is
        the path of any file or directory inside the wanted file system on
        the remote host.

     $arg = Quota::getqcarg($path)
        Get the required $dev argument for Quota::query and Quota::setqlim
        for the file system you want to operate on. $path is any path of
        an existing file or directory inside that file system. The path
        argument is optional and defaults to the current working directory.

        The type of $dev varies between operating systems, i.e. different
        implementations of the quotactl functionality. Hence it's important
        for compatibility to always use this module function and not really
        pass a device file to Quota::query (as returned by Quota::getdev).
        See also above at Quota::query

     $dev = Quota::getdev($path)
        Returns the device entry in the mount table for a particular file
        system, specified by any path of an existing file or directory
        inside it. $path defaults to the working directory. This device
        entry need not really be a device. For example on network mounts
        (NFS) it's "host:mountpath", with amd(1m) it may be something
        completely different.

        *NEVER* use this to produce a $dev argument for other functions of
        this module, since it's not compatible. On some systems quotactl
        does not work on devices but on the quotas file or some other kind
        of argument. Always use Quota::getqcarg.

     Quota::setmntent()
        Opens or resets the mount table. This is required before the first
        invocation of Quota::getmntent.

        Note: on some systems there is no equivalent function in the C
        library. But you still have to call this module procedure for
        initialization of module-internal variables.

     ($dev, $path, $type, $opts) = Quota::getmntent()
        Returns the next entry in the system mount table. This table
        contains information about all currently mounted (local or remote)
        file systems. The format and location of this table (e.g. /etc/mtab)
        vary from system to system. This function is provided as a
        compatible way to parse it. (On some systems, like OSF/1, this table
        isn't accessible as a file at all, i.e. only via Quota::getmntent).

     Quota::endmntent()
        Close the mount table. Should be called after the last use of
        Quota::getmntent to free possibly allocated file handles and memory.
        Always returns undef.

     Quota::strerr()
        Translates $! to a quota-specific error text. You should always use
        this function to output error messages, since the normal messages
        don't always make sense for quota errors (e.g. ESRCH: No such
        process, here: No quota for this user)

RETURN VALUES
        Functions that are supposed to return lists or scalars, return
	undef upon errors. As usual $! contains the error code (see
        Quota::strerr).

        Quota::endmntent always returns undef. All other functions return
        undef only upon errors.

EXAMPLES
        An example for each function can be found in the test script
        test/quotatest. See also the contrib directory, which contains
        some longer scripts, kindly donated by users of the module.

AUTHOR
        This module was written 1995 by Tom Zoerner
        (Tom.Zoerner@informatik.uni-erlangen.de)

        Additional testing and porting by David Lee (T.D.Lee@durham.ac.uk),
        Tobias Oetiker (oetiker@ee.ethz.ch) and Jim Hribnak
        (hribnak@nucleus.com)

SEE ALSO
        perl(1), edquota(1m), quotactl(2) or quotactl(7I), mount(1m),
        mtab(4) or mnttab(4), quotaon(1m), setmntent(3), getmntent(3) or
        getmntinfo(3), endmntent(3), rpc(3), rquotad(1m).

