Quota(3pm)

📦
version 1.8.2 · 6 versions
, in ubuntu stonking

✨ NAME ✨

Quota — it's the Perl interface to file system quotas, and honestly? iconic. 👑

(For the record, this lil page lives under User Contributed Perl Documentation, hence the 3pm in the corner. iykyk.)

🦋 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 🌈

So, the Quota module gives you access to file system quotas — you know, the thing that tells your users "bestie, you've had enough disk space for today." 💀

Under the hood it uses the quotactl system call or ioctl to query or set quotas on the local host, or it fires off queries via RPC to a remote host. Mount tables can be parsed with getmntent, and paths can be translated into device files (or literally whatever the actual quotactl implementations need as an argument) of the matching file system.

🌸 Functions 🌸

💫 ($bc,$bs,$bh,$bt, $ic,$is,$ih,$it) = Quota::query($dev, $uid, $kind)

Gets you the current usage and the quota limits for a given file system and user. The user is specified by their numeric uid, and it defaults to the process's real uid.

The type of $dev varies from system to system. It's the argument that the quotactl implementation uses to address a specific file system. It may be:

  • the path of a device file, e.g. /dev/sd0a
  • the path of the mount point
  • the quotas file at the top of the file system, e.g. /home.stand/quotas

But like, do not stress about it — just use Quota::getqcarg to automatically translate any path inside a file system into the required $dev argument. 🫶

$dev may also come in the form "hostname:path", which makes the module transparently query the given host over a remote procedure call (RPC). If you've got NFS (or similar network mounts), Quota::getqcarg can produce this style of argument too.

Note: RPC queries require rquotad(1m) to be running on the target system. If the daemon or the host is down, the timeout is 12 seconds. (yeah. twelve. bring a snack. 🍓)

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

Note: when the quota limits are not exceeded, those timestamps are meaningless and should be ignored. When hard and soft limits are both zero, that means there's 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 a gid and group quotas get 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 system).

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

💫 Quota::setqlim($dev, $uid, $bs,$bh, $is,$ih, $tlo, $kind)

Sets quota limits for the given user. The meanings of $dev, $uid, $bs, $bh, $is and $ih are exactly 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 get 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 a 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, because that's equivalent to unlimited access. 😭 Instead set only the hard limit to 0 and the soft limit, for example, to 1.
Note: you cannot set quotas via RPC.

💫 Quota::sync($dev)

Makes the kernel update the quota file on disk — or all quota files if no argument is given (tho heads up, that no-argument version 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 for how to enable quotas on a file system.

Note: on some systems this function always returns a success indication, even on partitions that don't have quotas enabled (e.g. Linux 2.4). This is not a bug in this module — it's a limitation in certain kernels. not us, not our problem 💅

💫 ($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. it queries the 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 the client side, the server side, or both. 🙃

💫 Quota::rpcpeer($port,$use_tcp,timeout)

Configures parameters for subsequent RPC queries — and every single one of those parameters is 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)

Configures authorization parameters for subsequent RPC queries — again, all parameters optional, we love a low-stakes signature. 💖 By default, uid and gid are taken from the owner of the process, and hostname is the host name of the current machine.

💫 $arg = Quota::getqcarg($path)

Gets you 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. So for compatibility it's super important to always use this module function and never 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", and 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's no equivalent function in the C library. But you still have to call this module procedure for initialization of module-internal variables. so yeah, call it anyway bestie 🫠

💫 ($dev, $path, $type, $opts) = Quota::getmntent()

Returns the next entry in the system mount table. This table holds info 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()

Closes 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 $! into 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 — but here it means: No quota for this user).

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

🎀 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 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. 🫶 (shoutout to the contributors, real ones.)

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

(part 1 of 2 — hold that thought, we're not done yet 💅)

✨ AUTHORS ✨

Okay so storytime bestie 🎀 — this module was created way back in 1995 by T. Zoerner (email: tomzo AT users.sourceforge.net), and ever since then it's been continually improved and ported to sooooo many operating- and file-systems. Literally a glow-up spanning decades. Iconic behavior. 👑

And it's not a solo act — numerous people have contributed to this whole process over the years. For a complete list of names please see the CHANGES document. 🫶

The quota module was in the public domain from 1995–2001. Then, since 2001, it's 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 its owner in regard to copyright. 💅

A repository for sources of this module lives at <https://github.com/tomzox/Perl-Quota>. And in April 2020 the module got ported to Python: <https://github.com/tomzox/Python-Quota>. Not her expanding her empire across languages 😭✨

🌸 SEE ALSO 🌸

The whole friend group, no cap:

Bestie we made it to the end and I'm so proud of you 🥹💖 One tiny last thing: this whole page is riding with perl v5.42.3, dated 2026-08-19, and it's filed under Quota(3pm). Read the manual, run the code, stay hydrated, slay. 🦋🍓
📦 where this page comes from