Provided by: libquota-perl_1.8.2+dfsg-3build2_amd64 bug

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 [,kind]]);

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

           Quota::rpcpeer([$port [,$use_tcp [,timeout]]]);

           Quota::rpcauth([$uid [,$gid [,$hostname]]]);

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

           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, $kind)
           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.

           Note: When the quota limits are not exceeded, the timestamps are meaningless and
           should be ignored.  When hard and soft limits are both zero, this means there is no
           limit for that user. (On some platforms the query may fail with error code ESRCH in
           that case; most however still report valid usage values.)

           When $kind is given and set to 1, the value in $uid is taken as gid and group quotas
           are queried. Group quotas may not be supported across all platforms (e.g. Linux and
           other BSD based Unix variants, OSF/1 and  AIX - check the quotactl(2) man page on your
           systems).

           When $kind is set to 2, project quotas are queried; this is currently only supported
           for XFS. When unsupported, this flag is ignored.

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

           For file systems exceeding 2 TB: To allow passing block or inode values larger or
           equal to 2^32 on 32-bit Perl versions, pass them either as strings or floating point.

           $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.

           When $kind is given and set to 1, $uid is taken as gid and group quota limits are set.
           This is not supported on all platforms (see above). When $kind is set to 2, project
           quotas are modified; this is currently only supported for XFS. When unsupported, this
           flag is ignored.

           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.

           Note: on some systems this function always returns a success indication, even on
           partitions which do not have quotas enabled (e.g. Linux 2.4).  This is not a bug in
           this module; it's a limitation in certain kernels.

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

           This is equivalent to "Quota::query("$host:$path",$uid,$kind)", 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 file system on the remote host.

           Querying group quotas ($kind = 1) is only recently supported on some platforms (e.g.
           on Linux via "extended" quota RPC, i.e. quota RPC version 2) so it may fail due to
           lack of support either on client or server side, or both.

       Quota::rpcpeer($port,$use_tcp,timeout)
           Configure parameters for subsequent RPC queries; all parameters are optional.  By
           default the portmapper on the remote host is used (i.e. default port is 0, protocol is
           UDP)  The default timeout is 4 seconds.

       Quota::rpcauth($uid,$gid,$hostname)
           Configure authorization parameters for subsequent RPC queries; all parameters are
           optional. By default uid and gid are taken from owner of the process and hostname is
           the host name of current machine.

       $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)

           Note that this function only returns a defined result if you called a Quota command
           directly before which returned an error indication.

RETURN VALUES

       Functions that are supposed 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 0 upon success, non-
       zero integer otherwise.

EXAMPLES

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

BUGS

       With remote quotas we have to rely on the remote system to state correctly which block
       size the quota values are referring to. Old versions of the Linux rpc.rquotad reported a
       block size of 4 kilobytes, which was wildly incorrect. For more info on this and other
       Linux bugs please see INSTALL.

AUTHORS

       This module was created 1995 by T. Zoerner (email: tomzo AT users.sourceforge.net) and
       since then continually improved and ported to many operating- and file-systems. Numerous
       people have contributed to this process; for a complete list of names please see the
       CHANGES document.

       The quota module was in the public domain 1995-2001. Since 2001 it is licensed under both
       the Perl Artistic License and version 1 or later of the GNU General Public License as
       published by the Free Software Foundation.  For a copy of these licenses see
       <http://www.opensource.org/licenses/>.  The respective authors of the source code are it's
       owner in regard to copyright.

       A repository for sources of this module is at <https://github.com/tomzox/Perl-Quota>. In
       April 2020 the module has been ported to Python: <https://github.com/tomzox/Python-Quota>

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).