Debian Codegraph @

README

raw
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