.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Quota 3"
.TH Quota 3 "2015-05-25" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Quota \- Perl interface to file system quotas
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBQuota\fR 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 \s-1RPC\s0 to a remote host.
Mount tables can be parsed with \fBgetmntent\fR and paths can be
translated to device files (or whatever the actual \fBquotactl\fR
implementations needs as argument) of the according file system.
.SS "Functions"
.IX Subsection "Functions"
.ie n .IP "\fI($bc,$bs,$bh,$bt, \fI$ic\fI,$is,$ih,$it) = Quota::query($dev, \f(CI$uid\fI, \f(CI$kind\fI)\fR" 4
.el .IP "\fI($bc,$bs,$bh,$bt, \f(CI$ic\fI,$is,$ih,$it) = Quota::query($dev, \f(CI$uid\fI, \f(CI$kind\fI)\fR" 4
.IX Item "($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.
.Sp
The type of \fI\f(CI$dev\fI\fR varies from system to system. It's the argument
which is used by the \fBquotactl\fR implementation to address a specific
file system. It may be the path of a device file (e.g. \fB/dev/sd0a\fR)
or the path of the mount point or the quotas file at the top of
the file system (e.g. \fB/home.stand/quotas\fR). However you do not
have to worry about that; use \fBQuota::getqcarg\fR to automatically
translate any path inside a file system to the required \fI\f(CI$dev\fI\fR argument.
.Sp
\&\fI\f(CI$dev\fI\fR may also be in the form of \fBhostname:path\fR, which has the
module transparently query the given host via a remote procedure call
(\s-1RPC\s0). In case you have \fB\s-1NFS\s0\fR (or similar network mounts), this type
of argument may also be produced by \fBQuota::getqcarg\fR. Note: \s-1RPC\s0
queries require \fI\fIrquotad\fI\|(1m)\fR to be running on the target system. If
the daemon or host are down, the timeout is 12 seconds.
.Sp
In \fI\f(CI$bc\fI\fR and \fI\f(CI$ic\fI\fR the current usage in blocks and inodes is returned.
\&\fI\f(CI$bs\fI\fR and \fI\f(CI$is\fI\fR are the soft limits, \fI\f(CI$bh\fI\fR and \fI\f(CI$ih\fI\fR hard limits. If the
soft limit is exceeded, writes by this user will fail for blocks or
inodes after \fI\f(CI$bt\fI\fR or \fI\f(CI$it\fI\fR is reached. These times are expressed
as usual, i.e. in elapsed seconds since 00:00 1/Jan/1970 \s-1GMT.\s0
.Sp
Note: When the quota limits are not exceeded, the timestamps
are meaningless and should be ignored. When hard and soft
limits are zero, there is no limit for that user. On most
systems Quota::query will return undef in that case and
errno will be set to \s-1ESRCH.\s0
.Sp
When \fI\f(CI$kind\fI\fR is given and set to 1, \fI\f(CI$uid\fI\fR is taken as gid and
group quotas are queried. This is \fBnot\fR supported across \s-1RPC\s0 and
even locally only on a few architectures (e.g. Linux and other \s-1BSD\s0
based Unix variants, \s-1OSF/1\s0 and  \s-1AIX \-\s0 check the \fIquotactl\fR\|(2) man page
on your systems). When \fI\f(CI$kind\fI\fR is set to 2, project quotas are
queried; this is currently only supported for \s-1XFS. \s0 When unsupported,
this flag is ignored.
.ie n .IP "\fIQuota::setqlim($dev, \fI$uid\fI, \f(CI$bs\fI,$bh, \f(CI$is\fI,$ih, \f(CI$tlo\fI, \f(CI$kind\fI)\fR" 4
.el .IP "\fIQuota::setqlim($dev, \f(CI$uid\fI, \f(CI$bs\fI,$bh, \f(CI$is\fI,$ih, \f(CI$tlo\fI, \f(CI$kind\fI)\fR" 4
.IX Item "Quota::setqlim($dev, $uid, $bs,$bh, $is,$ih, $tlo, $kind)"
Sets quota limits for the given user. Meanings of \fI\f(CI$dev\fI\fR, \fI\f(CI$uid\fI\fR,
\&\fI\f(CI$bs\fI\fR, \fI\f(CI$bh\fI\fR, \fI\f(CI$is\fI\fR and \fI\f(CI$ih\fI\fR are the same as in \fBQuota::query\fR.
.Sp
For file systems exceeding 2 \s-1TB:\s0 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.
.Sp
\&\fI\f(CI$tlo\fI\fR decides how the time limits are initialized:
\&\fI0\fR: The time limits are set to \fB\s-1NOT STARTED\s0\fR, i.e. the time limits
are not initialized until the first write attempt by this user.
This is the default.
\&\fI1\fR: The time limits are set to \fB7.0 days\fR.
More alternatives (i.e. setting a specific time) aren't available in
most implementations.
.Sp
When \fI\f(CI$kind\fI\fR is given and set to 1, \fI\f(CI$uid\fI\fR is taken as gid and
group quota limits are set. This is supported only on a few
architectures (see above). When \fI\f(CI$kind\fI\fR is set to 2, project
quotas are modified; this is currently only supported for \s-1XFS.\s0
When unsupported, this flag is ignored.
.Sp
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.
.Sp
Note that you cannot set quotas via \s-1RPC.\s0
.IP "\fIQuota::sync($dev)\fR" 4
.IX Item "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 \fBHP-UX 10.10\fR).
.Sp
The main purpose of this function is to check if quota is enabled
in the kernel and for a particular file system. Read the \fB\f(BIquotaon\fB\|(1m)\fR
man page on how to enable quotas on a file system.
.Sp
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.
.ie n .IP "\fI($bc,$bs,$bh,$bt, \fI$ic\fI,$is,$ih,$it) =\fR" 4
.el .IP "\fI($bc,$bs,$bh,$bt, \f(CI$ic\fI,$is,$ih,$it) =\fR" 4
.IX Item "($bc,$bs,$bh,$bt, $ic,$is,$ih,$it) ="
\&\fIQuota::rpcquery($host,$path,$uid,$kind)\fR
.Sp
This is equivalent to \fBQuota::query(\*(L"$host:$path\*(R",$uid,$kind)\fR, i.e.
query quota for a given user on a given remote host via \s-1RPC.
\&\s0\fI\f(CI$path\fI\fR 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
\&\*(L"extended\*(R" quota \s-1RPC,\s0 i.e. quota \s-1RPC\s0 version 2) so it may fail due
to lack of support either on client or server side, or both.
.IP "\fIQuota::rpcpeer($port,$use_tcp,timeout)\fR" 4
.IX Item "Quota::rpcpeer($port,$use_tcp,timeout)"
Configure parameters for subsequent \s-1RPC\s0 queries; all parameters are
optional.  By default the portmapper on the remote host is used
(i.e. default port is 0, protocol is \s-1UDP\s0)  The default timeout is
4 seconds.
.IP "\fIQuota::rpcauth($uid,$gid,$hostname)\fR" 4
.IX Item "Quota::rpcauth($uid,$gid,$hostname)"
Configure authorization parameters for subsequent \s-1RPC\s0 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.
.ie n .IP "\fI\fI$arg\fI = Quota::getqcarg($path)\fR" 4
.el .IP "\fI\f(CI$arg\fI = Quota::getqcarg($path)\fR" 4
.IX Item "$arg = Quota::getqcarg($path)"
Get the required \fI\f(CI$dev\fI\fR argument for \fBQuota::query\fR and \fBQuota::setqlim\fR
for the file system you want to operate on. \fI\f(CI$path\fI\fR 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.
.Sp
The type of \fI\f(CI$dev\fI\fR 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 \fBQuota::query\fR (as returned by \fBQuota::getdev\fR).
See also above at \fIQuota::query\fR
.ie n .IP "\fI\fI$dev\fI = Quota::getdev($path)\fR" 4
.el .IP "\fI\f(CI$dev\fI = Quota::getdev($path)\fR" 4
.IX Item "$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. \fI\f(CI$path\fI\fR
defaults to the working directory. This device entry need not really be
a device. For example on network mounts (\fB\s-1NFS\s0\fR) it's \fI\*(L"host:mountpath\*(R"\fR,
with \fI\fIamd\fI\|(1m)\fR it may be something completely different.
.Sp
\&\fI\s-1NEVER\s0\fR use this to produce a \fI\f(CI$dev\fI\fR argument for other functions of
this module, since it's not compatible. On some systems \fIquotactl\fR
does not work on devices but on the \fIquotas\fR file or some other kind of
argument. Always use \fBQuota::getqcarg\fR.
.IP "\fI\fIQuota::setmntent()\fI\fR" 4
.IX Item "Quota::setmntent()"
Opens or resets the mount table. This is required before the first
invocation of \fBQuota::getmntent\fR.
.Sp
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.
.ie n .IP "\fI($dev, \fI$path\fI, \f(CI$type\fI, \f(CI$opts\fI) = \fIQuota::getmntent()\fI\fR" 4
.el .IP "\fI($dev, \f(CI$path\fI, \f(CI$type\fI, \f(CI$opts\fI) = \fIQuota::getmntent()\fI\fR" 4
.IX Item "($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. \fB/etc/mtab\fR) vary from
system to system. This function is provided as a compatible way to
parse it. (On some systems, like \fB\s-1OSF/1\s0\fR, this table isn't
accessible as a file at all, i.e. only via \fBQuota::getmntent\fR).
.IP "\fI\fIQuota::endmntent()\fI\fR" 4
.IX Item "Quota::endmntent()"
Close the mount table. Should be called after the last use of
\&\fBQuota::getmntent\fR to free possibly allocated file handles and memory.
Always returns undef.
.IP "\fI\fIQuota::strerr()\fI\fR" 4
.IX Item "Quota::strerr()"
Translates \fB$!\fR 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. \fI\s-1ESRCH\s0\fR: \fBNo such process\fR, here: \fBNo quota for this user\fR)
.Sp
Note that this function only returns a defined result if you called a
Quota command directly before which returned an error indication.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
Functions that are supposed return lists or scalars, return \fIundef\fR upon
errors. As usual \fB$!\fR contains the error code (see \fBQuota::strerr\fR).
.PP
\&\fBQuota::endmntent\fR always returns \fIundef\fR.
All other functions return 0 upon success, non-zero integer otherwise.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
An example for each function can be found in the test script
\&\fItest.pl\fR. See also the contrib directory, which contains
some longer scripts, kindly donated by users of the module.
.SH "BUGS"
.IX Header "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 \s-1INSTALL.\s0
.SH "AUTHORS"
.IX Header "AUTHORS"
This module was created 1995 by Tom Zoerner
(email: tomzo \s-1AT\s0 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 \s-1CHANGES\s0 document.
.PP
The quota module was in the public domain 1995\-2001. Since 2001 it is
licensed under both the Perl Artistic License and version 2 or later of the
\&\s-1GNU\s0 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \fIedquota\fR\|(1m),
\&\fIquotactl\fR\|(2) or quotactl(7I),
\&\fImount\fR\|(1m), \fImtab\fR\|(4) or \fImnttab\fR\|(4), \fIquotaon\fR\|(1m),
\&\fIsetmntent\fR\|(3), \fIgetmntent\fR\|(3) or \fIgetmntinfo\fR\|(3), \fIendmntent\fR\|(3),
\&\fIrpc\fR\|(3), \fIrquotad\fR\|(1m).