| 1 |
Quota extension module for Perl |
| 2 |
------------------------------- |
| 3 |
|
| 4 |
Author: T. Zoerner (tomzo AT users.sourceforge.net) |
| 5 |
|
| 6 |
Version: 1.8.2 |
| 7 |
Date: October 2021 |
| 8 |
DLSIP-Code:Rcdfg |
| 9 |
- stable release |
| 10 |
- C compiler required for installation |
| 11 |
- support by developer |
| 12 |
- plain functions, no references used |
| 13 |
- licensed under the Perl Artistic License or |
| 14 |
(at your option) version 2 or later of the |
| 15 |
GNU General Public License |
| 16 |
Location: https://metacpan.org/pod/Quota |
| 17 |
Repository:https://github.com/tomzox/Perl-Quota |
| 18 |
|
| 19 |
Supported: SunOS 4.1.3, |
| 20 |
Solaris 2.4 - 2.10, |
| 21 |
HP-UX 9.0x & 10.10 & 10.20 & 11.00, |
| 22 |
IRIX 5.2 & 5.3 & 6.2 - 6.5, |
| 23 |
OSF/1 & Digital Unix 4, |
| 24 |
FreeBSD 3 - 12.1, OpenBSD 2.2 - 6.6 & NetBSD 5 - 9, |
| 25 |
Linux - kernel 2.0.30 - 4.15, |
| 26 |
AIX 4.1, 4.2 and 5.3. |
| 27 |
|
| 28 |
Standard file systems of the platforms listed above, |
| 29 |
NFS (Network file system) on all of the above, |
| 30 |
XFS on Linux and IRIX 6, |
| 31 |
AFS (Andrew File System) on many of the above (see INSTALL), |
| 32 |
VxFS (Veritas File System) on Solaris 2. |
| 33 |
|
| 34 |
Documentation is in pod format at the end of Quota.pm, |
| 35 |
installation hints are in a file named INSTALL inside this package. |
| 36 |
See also CHANGES for a history of updates to this module. |
| 37 |
|
| 38 |
----------------------------------------------------------------------------- |
| 39 |
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR |
| 40 |
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED |
| 41 |
WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 42 |
----------------------------------------------------------------------------- |
| 43 |
|
| 44 |
|
| 45 |
NAME |
| 46 |
Quota - Perl interface to file system quotas |
| 47 |
|
| 48 |
SYNOPSIS |
| 49 |
use Quota; |
| 50 |
|
| 51 |
($block_curr, $block_soft, $block_hard, $block_timelimit, |
| 52 |
$inode_curr, $inode_soft, $inode_hard, $inode_timelimit) = |
| 53 |
Quota::query($dev [,$uid [,kind]]); |
| 54 |
|
| 55 |
($block_curr, $block_soft, $block_hard, $block_timelimit, |
| 56 |
$inode_curr, $inode_soft, $inode_hard, $inode_timelimit) = |
| 57 |
Quota::rpcquery($host, $path [,$uid [,kind]]); |
| 58 |
|
| 59 |
Quota::rpcpeer([$port [,$use_tcp [,timeout]]]); |
| 60 |
|
| 61 |
Quota::setqlim($dev, $uid, $block_soft, $block_hard, |
| 62 |
$inode_soft, $inode_hard [,$tlo [,kind]]); |
| 63 |
|
| 64 |
Quota::sync([$dev]); |
| 65 |
|
| 66 |
$arg = Quota::getqcarg([$path]); |
| 67 |
|
| 68 |
Quota::setmntent(); |
| 69 |
($dev, $path, $type, $opts) = Quota::getmntent(); |
| 70 |
Quota::endmntent(); |
| 71 |
|
| 72 |
|
| 73 |
DESCRIPTION |
| 74 |
The Quota module provides access to file system quotas. The |
| 75 |
quotactl system call or ioctl is used to query or set quotas |
| 76 |
on the local host, or queries are submitted via RPC to a |
| 77 |
remote host. Mount tables can be parsed with getmntent and |
| 78 |
paths can be translated to device files (or whatever the |
| 79 |
actual quotactl implementations needs as argument) of the |
| 80 |
according file system. |
| 81 |
|
| 82 |
Functions |
| 83 |
|
| 84 |
($bc,$bs,$bh,$bt, $ic,$is,$ih,$it) = Quota::query($dev, $uid, $kind) |
| 85 |
Get current usage and quota limits for a given file |
| 86 |
system and user. The user is specified by its numeric |
| 87 |
uid; defaults to the process' real uid. |
| 88 |
|
| 89 |
The type of $dev varies from system to system. It's the |
| 90 |
argument which is used by the quotactl implementation to |
| 91 |
address a specific file system. It may be the path of a |
| 92 |
device file (e.g. /dev/sd0a) or the path of the mount |
| 93 |
point or the quotas file at the top of the file system |
| 94 |
(e.g. /home.stand/quotas). However you do not have to |
| 95 |
worry about that; use Quota::getqcarg to automatically |
| 96 |
translate any path inside a file system to the required |
| 97 |
$dev argument. |
| 98 |
|
| 99 |
$dev may also be in the form of hostname:path, which has |
| 100 |
the module transparently query the given host via a |
| 101 |
remote procedure call (RPC). In case you have NFS (or |
| 102 |
similar network mounts), this type of argument may also |
| 103 |
be produced by Quota::getqcarg. Note: RPC queries |
| 104 |
require rquotad(1m) to be running on the target system. |
| 105 |
If the daemon or host are down, the timeout is 12 |
| 106 |
seconds. |
| 107 |
|
| 108 |
In $bc and $ic the current usage in blocks and inodes is |
| 109 |
returned. $bs and $is are the soft limits, $bh and $ih |
| 110 |
hard limits. If the soft limit is exceeded, writes by |
| 111 |
this user will fail for blocks or inodes after $bt or |
| 112 |
$it is reached. These times are expressed as usual, i.e. |
| 113 |
in elapsed seconds since 00:00 1/Jan/1970 GMT. |
| 114 |
|
| 115 |
Note: When the quota limits are not exceeded, the timestamps |
| 116 |
are meaningless and should be ignored. When hard and soft |
| 117 |
limits are zero, there is no limit for that user. On most |
| 118 |
systems Quota::query will return undef in that case and |
| 119 |
errno will be set to ESRCH. |
| 120 |
|
| 121 |
When $kind is given and set to 1, the value in $uid is taken |
| 122 |
as gid and group quotas are queried. Group quotas may not be |
| 123 |
supported across all platforms (e.g. Linux and other BSD |
| 124 |
based Unix variants, OSF/1 and AIX - check the quotactl(2) |
| 125 |
man page on your systems). |
| 126 |
|
| 127 |
When $kind is set to 2, project quotas are queried; this is |
| 128 |
currently only supported for XFS. When unsupported, this flag |
| 129 |
is ignored. |
| 130 |
|
| 131 |
Quota::setqlim($dev, $uid, $bs,$bh, $is,$ih, $tlo, $kind) |
| 132 |
Sets quota limits for the given user. Meanings of $dev, |
| 133 |
$uid, $bs, $bh, $is and $ih are the same as in |
| 134 |
Quota::query. |
| 135 |
|
| 136 |
For file systems exceeding 2 TB: To allow passing block or |
| 137 |
inode values larger or equal to 2^32 on 32-bit Perl versions, |
| 138 |
pass them either as strings or floating point. |
| 139 |
|
| 140 |
$tlo decides how the time limits are initialized: 0: |
| 141 |
The time limits are set to NOT STARTED, i.e. the time |
| 142 |
limits are not initialized until the first write attempt |
| 143 |
by this user. This is the default. 1: The time limits |
| 144 |
are set to 7.0 days. More alternatives (i.e. setting a |
| 145 |
specific time) aren't available in most implementations. |
| 146 |
|
| 147 |
When $kind is given and set to 1, $uid is taken as gid and |
| 148 |
group quota limits are set. This is not supported on all |
| 149 |
platforms (see above). When $kind is set to 2, project quotas |
| 150 |
are modified; this is currently only supported for XFS. When |
| 151 |
unsupported, this flag is ignored. |
| 152 |
|
| 153 |
Note: if you want to set the quota of a particular user |
| 154 |
to zero, i.e. no write permission, you must not set all |
| 155 |
limits to zero, since that is equivalent to unlimited |
| 156 |
access. Instead set only the hard limit to 0 and the |
| 157 |
soft limit for example to 1. |
| 158 |
|
| 159 |
Note that you cannot set quotas via RPC. |
| 160 |
|
| 161 |
Quota::sync($dev) |
| 162 |
Have the kernel update the quota file on disk or all |
| 163 |
quota files if no argument given (the latter doesn't |
| 164 |
work on all systems, in particular on HP-UX 10.10). |
| 165 |
|
| 166 |
The main purpose of this function is to check if quota |
| 167 |
is enabled in the kernel and for a particular file |
| 168 |
system. Read the quotaon(1m) man page on how to enable |
| 169 |
quotas on a file system. |
| 170 |
|
| 171 |
Note: on some systems this function always returns a |
| 172 |
success indication, even on partitions which do not |
| 173 |
have quotas enabled (e.g. Linux). This is not a bug |
| 174 |
in this module; it's a limitation in certain kernels. |
| 175 |
|
| 176 |
($bc,$bs,$bh,$bt, $ic,$is,$ih,$it) = |
| 177 |
Quota::rpcquery($host,$path,$uid,$kind) |
| 178 |
|
| 179 |
This is equivalent to Quota::query("$host:$path",$uid,$kind), |
| 180 |
i.e. query quota for a given user on a given remote |
| 181 |
host via RPC. $path is the path of any file or |
| 182 |
directory inside the wanted file system on the remote |
| 183 |
host. |
| 184 |
|
| 185 |
Querying group quotas ($kind = 1) is only recently supported |
| 186 |
on some platforms (e.g. on Linux via "extended" quota RPC, |
| 187 |
i.e. quota RPC version 2) so it may fail due to lack of |
| 188 |
support either on client or server side, or both. |
| 189 |
|
| 190 |
Quota::rpcpeer($port,$use_tcp,timeout) |
| 191 |
Configure parameters for subsequent RPC queries; all |
| 192 |
parameters are optional. By default the portmapper on |
| 193 |
the remote host is used (i.e. default port is 0, |
| 194 |
protocol is UDP) The default timeout is 4 seconds. |
| 195 |
|
| 196 |
Quota::rpcauth($uid,$gid,$hostname) |
| 197 |
Configure authorization parameters for subsequent |
| 198 |
RPC queries; all parameters are optional. By default |
| 199 |
uid and gid are taken from owner of the process and |
| 200 |
hostname is the host name of current machine. |
| 201 |
|
| 202 |
$arg = Quota::getqcarg($path) |
| 203 |
Get the required $dev argument for Quota::query and |
| 204 |
Quota::setqlim for the file system you want to operate |
| 205 |
on. $path is any path of an existing file or directory |
| 206 |
inside that file system. The path argument is optional |
| 207 |
and defaults to the current working directory. |
| 208 |
|
| 209 |
The type of $dev varies between operating systems, i.e. |
| 210 |
different implementations of the quotactl functionality. |
| 211 |
Hence it's important for compatibility to always use |
| 212 |
this module function and not really pass a device file |
| 213 |
to Quota::query (as returned by Quota::getdev). See |
| 214 |
also above at Quota::query |
| 215 |
|
| 216 |
$dev = Quota::getdev($path) |
| 217 |
Returns the device entry in the mount table for a |
| 218 |
particular file system, specified by any path of an |
| 219 |
existing file or directory inside it. $path defaults to |
| 220 |
the working directory. This device entry need not really |
| 221 |
be a device. For example on network mounts (NFS) it's |
| 222 |
"host:mountpath", with amd(1m) it may be something |
| 223 |
completely different. |
| 224 |
|
| 225 |
NEVER use this to produce a $dev argument for other |
| 226 |
functions of this module, since it's not compatible. On |
| 227 |
some systems quotactl does not work on devices but on |
| 228 |
the quotas file or some other kind of argument. Always |
| 229 |
use Quota::getqcarg. |
| 230 |
|
| 231 |
Quota::setmntent() |
| 232 |
Opens or resets the mount table. This is required before |
| 233 |
the first invocation of Quota::getmntent. |
| 234 |
|
| 235 |
Note: on some systems there is no equivalent function in |
| 236 |
the C library. But you still have to call this module |
| 237 |
procedure for initialization of module-internal |
| 238 |
variables. |
| 239 |
|
| 240 |
($dev, $path, $type, $opts) = Quota::getmntent() |
| 241 |
Returns the next entry in the system mount table. This |
| 242 |
table contains information about all currently mounted |
| 243 |
(local or remote) file systems. The format and location |
| 244 |
of this table (e.g. /etc/mtab) vary from system to |
| 245 |
system. This function is provided as a compatible way to |
| 246 |
parse it. (On some systems, like OSF/1, this table isn't |
| 247 |
accessible as a file at all, i.e. only via |
| 248 |
Quota::getmntent). |
| 249 |
|
| 250 |
Quota::endmntent() |
| 251 |
Close the mount table. Should be called after the last |
| 252 |
use of Quota::getmntent to free possibly allocated file |
| 253 |
handles and memory. Always returns undef. |
| 254 |
|
| 255 |
Quota::strerr() |
| 256 |
Translates $! to a quota-specific error text. You should |
| 257 |
always use this function to output error messages, since |
| 258 |
the normal messages don't always make sense for quota |
| 259 |
errors (e.g. ESRCH: No such process, here: No quota for |
| 260 |
this user) |
| 261 |
|
| 262 |
Note that this function only returns a defined result if |
| 263 |
you called a Quota command directly before which returned |
| 264 |
an error indication. |
| 265 |
|
| 266 |
RETURN VALUES |
| 267 |
Functions that are supposed return lists or scalars, return |
| 268 |
undef upon errors. As usual $! contains the error code (see |
| 269 |
Quota::strerr). |
| 270 |
|
| 271 |
Quota::endmntent always returns undef. All other functions |
| 272 |
return 0 upon success, non-zero integer otherwise. |
| 273 |
|
| 274 |
EXAMPLES |
| 275 |
An example for each function can be found in the test script |
| 276 |
test.pl. See also the contrib directory, which contains |
| 277 |
some longer scripts, kindly donated by users of the module. |
| 278 |
|
| 279 |
BUGS |
| 280 |
With remote quotas we have to rely on the remote system to |
| 281 |
state correctly which block size the quota values are |
| 282 |
referring to. Old versions of the Linux rpc.rquotad |
| 283 |
reported a block size of 4 kilobytes, which was wildly |
| 284 |
incorrect. For more info on this and other Linux bugs please |
| 285 |
see INSTALL. |
| 286 |
|
| 287 |
AUTHORS |
| 288 |
This module was created 1995 by T. Zoerner |
| 289 |
(email: tomzo AT users.sourceforge.net) |
| 290 |
and since then continually improved and ported to |
| 291 |
many operating- and file-systems. Numerous people |
| 292 |
have contributed to this process; for a complete |
| 293 |
list of names please see the CHANGES document. |
| 294 |
|
| 295 |
The quota module was in the public domain 1995-2001. Since 2001 |
| 296 |
it is licensed under both the Perl Artistic License and version 1 |
| 297 |
or later of the GNU General Public License as published by the |
| 298 |
Free Software Foundation. For a copy of these licenses see |
| 299 |
<http://www.opensource.org/licenses/>. The respective authors |
| 300 |
of the source code are its owner in regard to copyright. |
| 301 |
|
| 302 |
SEE ALSO |
| 303 |
perl(1), edquota(1m), quotactl(2) or quotactl(7I), |
| 304 |
mount(1m), mtab(4) or mnttab(4), quotaon(1m), setmntent(3), |
| 305 |
getmntent(3) or getmntinfo(3), endmntent(3), rpc(3), |
| 306 |
rquotad(1m). |
| 307 |
|