]>
Commit | Line | Data |
---|---|---|
1eeddf25 JK |
1 | .\" Copyright (c) 2010, Jan Kara |
2 | .\" A few pieces copyright (c) 1996 Andries Brouwer (aeb@cwi.nl) | |
3 | .\" and copyright 2010 (c) Michael Kerrisk <mtk.manpages@gmail.com> | |
fea681da MK |
4 | .\" |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
1eeddf25 JK |
9 | .\" Permission is granted to copy and distribute modified versions of |
10 | .\" this manual under the conditions for verbatim copying, provided that | |
11 | .\" the entire resulting derived work is distributed under the terms of | |
12 | .\" a permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da | 14 | .\" Since the Linux kernel and libraries are constantly changing, this |
1eeddf25 JK |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume. |
16 | .\" no responsibility for errors or omissions, or for damages resulting. | |
17 | .\" from the use of the information contained herein. The author(s) may. | |
18 | .\" not have taken the same level of care in the production of this. | |
19 | .\" manual, which is licensed free of charge, as they might when working. | |
fea681da | 20 | .\" professionally. |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" | |
1eeddf25 | 25 | .TH QUOTACTL 2 2010-06-16 "Linux" "Linux Programmer's Manual" |
fea681da | 26 | .SH NAME |
1eeddf25 | 27 | quotactl \- manipulate disk quotas |
fea681da | 28 | .SH SYNOPSIS |
cb2431bf | 29 | .nf |
fea681da | 30 | .B #include <sys/quota.h> |
1eeddf25 JK |
31 | .B #include <xfs/xqm.h> |
32 | .LP | |
cb2431bf MK |
33 | .BI "int quotactl(int " cmd ", const char *" special ", int " id \ |
34 | ", caddr_t " addr ); | |
cb2431bf | 35 | .fi |
fea681da | 36 | .SH DESCRIPTION |
1eeddf25 JK |
37 | .LP |
38 | The quota system can be used to set per-user and per-group limits on the | |
39 | amount of disk space used on a file system. | |
40 | For each user and/or group, | |
41 | a soft limit and a hard limit can be set for each file system. | |
42 | The hard limit can't be exceeded. | |
43 | The soft limit can be exceeded, but warnings will ensue. | |
44 | Moreover, the user can't exceed the soft limit for more than one week | |
45 | (by default) at a time; | |
46 | after this time, the soft limit counts as a hard limit. | |
fea681da MK |
47 | |
48 | The | |
e511ffb6 | 49 | .BR quotactl () |
1eeddf25 JK |
50 | call manipulates disk quotas. |
51 | The | |
52 | .I cmd | |
53 | argument indicates a command to be applied to the user or | |
54 | group ID specified in | |
55 | .IR id . | |
56 | To initialize the | |
57 | .IR cmd | |
58 | argument, use the | |
59 | .IR "QCMD(subcmd, type)" | |
60 | macro. | |
61 | The | |
fea681da | 62 | .I type |
1eeddf25 JK |
63 | value is either |
64 | .BR USRQUOTA , | |
65 | for user quotas, | |
fea681da | 66 | or |
1eeddf25 JK |
67 | .BR GRPQUOTA , |
68 | for group quotas. | |
69 | The | |
fea681da | 70 | .I subcmd |
1eeddf25 | 71 | value is described below. |
fea681da | 72 | |
1eeddf25 | 73 | The |
fea681da | 74 | .I special |
1eeddf25 JK |
75 | argument is a pointer to a null-terminated string containing the pathname |
76 | of the (mounted) block special device for the file system being manipulated. | |
fea681da | 77 | |
1eeddf25 | 78 | The |
fea681da | 79 | .I addr |
1eeddf25 JK |
80 | argument is the address of an optional, command-specific, data structure |
81 | that is copied in or out of the system. | |
82 | The interpretation of | |
83 | .I addr | |
84 | is given with each command below. | |
fea681da MK |
85 | |
86 | The | |
87 | .I subcmd | |
1eeddf25 JK |
88 | value is one of the following: |
89 | .TP 8 | |
5a11d358 | 90 | .B Q_QUOTAON |
1eeddf25 | 91 | Turn on quotas for a file system. |
c13182ef | 92 | The |
1eeddf25 JK |
93 | .I id |
94 | argument is the identification number of the quota format to be used. | |
95 | Currently, there are three supported quota formats: | |
96 | .RS | |
97 | .TP 13 | |
98 | .BR QFMT_VFS_OLD | |
99 | The original quota format. | |
fea681da | 100 | .TP |
1eeddf25 JK |
101 | .BR QFMT_VFS_V0 |
102 | The standard VFS v0 quota format, which can handle 32-bit UIDs and GIDs | |
103 | and quota limits up to 2^42 bytes and 2^32 inodes. | |
104 | .TP | |
105 | .BR QFMT_VFS_V1 | |
106 | A quota format that can handle 32-bit UIDs and GIDs | |
107 | and quota limits of 2^64 bytes and 2^64 inodes. | |
108 | .RE | |
109 | .IP | |
110 | The | |
111 | .IR addr | |
112 | argument points to the pathname of a file containing the quotas for | |
113 | the file system. | |
114 | The quota file must exist; it is normally created with the | |
115 | .BR quotacheck (8) | |
116 | program. | |
117 | This operation requires privilege | |
118 | .RB ( CAP_SYS_ADMIN ). | |
119 | .TP 8 | |
fea681da | 120 | .B Q_QUOTAOFF |
1eeddf25 JK |
121 | Turn off quotas for a file system. |
122 | The | |
123 | .I addr | |
124 | and | |
125 | .I id | |
126 | arguments are ignored. | |
127 | This operation requires privilege | |
128 | .RB ( CAP_SYS_ADMIN ). | |
fea681da MK |
129 | .TP |
130 | .B Q_GETQUOTA | |
1eeddf25 JK |
131 | Get disk quota limits and current usage for user or group |
132 | .IR id . | |
c13182ef | 133 | The |
fea681da | 134 | .I addr |
1eeddf25 JK |
135 | argument is a pointer to a |
136 | .I dqblk | |
137 | structure defined in | |
138 | .IR <sys/quota.h> | |
139 | as follows: | |
140 | .in +4n | |
141 | .nf | |
142 | ||
22187ccf MK |
143 | /* uint64_t is an unsigned 64-bit integer; |
144 | uint32_t is an unsigned 32-bit integer */ | |
1eeddf25 JK |
145 | |
146 | struct dqblk { /* Definition since Linux 2.4.22 */ | |
147 | uint64_t dqb_bhardlimit; /* absolute limit on disk | |
148 | quota blocks alloc */ | |
149 | uint64_t dqb_bsoftlimit; /* preferred limit on | |
150 | disk quota blocks */ | |
151 | uint64_t dqb_curspace; /* current quota block | |
152 | count */ | |
153 | uint64_t dqb_ihardlimit; /* maximum number of | |
154 | allocated inodes */ | |
155 | uint64_t dqb_isoftlimit; /* preferred inode limit */ | |
156 | uint64_t dqb_curinodes; /* current number of | |
157 | allocated inodes */ | |
158 | uint64_t dqb_btime; /* time limit for excessive | |
159 | disk use */ | |
160 | uint64_t dqb_itime; /* time limit for excessive | |
161 | files */ | |
162 | uint32_t dqb_valid; /* bit mask of QIF_* | |
163 | constants */ | |
164 | }; | |
165 | ||
166 | /* Flags in dqb_valid that indicate which fields in | |
167 | dqblk structure are valid. */ | |
168 | ||
169 | #define QIF_BLIMITS 1 | |
170 | #define QIF_SPACE 2 | |
171 | #define QIF_ILIMITS 4 | |
172 | #define QIF_INODES 8 | |
173 | #define QIF_BTIME 16 | |
174 | #define QIF_ITIME 32 | |
175 | #define QIF_LIMITS (QIF_BLIMITS | QIF_ILIMITS) | |
176 | #define QIF_USAGE (QIF_SPACE | QIF_INODES) | |
177 | #define QIF_TIMES (QIF_BTIME | QIF_ITIME) | |
178 | #define QIF_ALL (QIF_LIMITS | QIF_USAGE | QIF_TIMES) | |
179 | ||
180 | .fi | |
181 | .in | |
182 | The | |
183 | .I dqb_valid | |
184 | field is a bit mask that is set to indicate the entries in the | |
185 | .I dqblk | |
186 | structure that are valid. | |
187 | Currently, the kernel fills in all entries of the | |
188 | .I dqblk | |
189 | structure and marks them as valid in the | |
190 | .I dqb_valid | |
191 | field. | |
192 | Unprivileged users may retrieve only their own quotas; | |
193 | a privileged user | |
194 | .RB ( CAP_SYS_ADMIN ) | |
195 | can retrieve the quotas of any user. | |
fea681da MK |
196 | .TP |
197 | .B Q_SETQUOTA | |
1eeddf25 JK |
198 | Set quota information for user or group |
199 | .IR id , | |
200 | using the information supplied in the | |
201 | .I dqblk | |
202 | structure pointed to by | |
203 | .IR addr . | |
204 | The | |
205 | .I dqb_valid | |
206 | field of the | |
207 | .I dqblk | |
208 | structure indicates which entries in the structure have been set by the caller. | |
209 | This operation supersedes the | |
210 | .B Q_SETQLIM | |
211 | and | |
212 | .B Q_SETUSE | |
213 | operations in the previous quota interfaces. | |
214 | This operation requires privilege | |
215 | .RB ( CAP_SYS_ADMIN ). | |
216 | .TP | |
217 | .B Q_GETINFO | |
218 | Get information (like grace times) about quotafile. | |
219 | The | |
fea681da | 220 | .I addr |
1eeddf25 JK |
221 | argument should be a pointer to a |
222 | .I dqinfo | |
223 | structure. | |
224 | This structure is defined in | |
225 | .IR <sys/quota.h> | |
226 | as follows: | |
227 | .in +4n | |
228 | .nf | |
229 | ||
230 | /* uint64_t is an unsigned 64-bit integer; | |
231 | uint32_t is an unsigned 32-bit integer */ | |
232 | ||
233 | struct dqinfo { /* Defined since kernel 2.4.22 */ | |
234 | uint64_t dqi_bgrace; /* Time before block soft limit | |
235 | becomes hard limit */ | |
236 | ||
237 | uint64_t dqi_igrace; /* Time before inode soft limit | |
238 | becomes hard limit */ | |
239 | uint32_t dqi_flags; /* Flags for quotafile | |
240 | (DQF_*) */ | |
241 | uint32_t dqi_valid; | |
242 | }; | |
243 | ||
244 | /* Bits for dqi_flags */ | |
245 | ||
b09639d9 MK |
246 | /* Quota format QFMT_VFS_OLD */ |
247 | ||
248 | #define V1_DQF_RSQUASH 1 /* Root squash enabled */ | |
249 | ||
250 | /* Other quota formats have no dqi_flags bits defined */ | |
1eeddf25 JK |
251 | |
252 | /* Flags in dqi_valid that indicate which fields in | |
253 | dqinfo structure are valid. */ | |
254 | ||
255 | # define IIF_BGRACE 1 | |
256 | # define IIF_IGRACE 2 | |
257 | # define IIF_FLAGS 4 | |
258 | # define IIF_ALL (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS) | |
259 | ||
260 | .fi | |
261 | .in | |
262 | The | |
263 | .I dqi_valid | |
264 | field in the | |
265 | .I dqinfo | |
266 | structure indicates the entries in the structure that are valid. | |
267 | Currently, the kernel fills in all entries of the | |
268 | .I dqinfo | |
269 | structure and marks them all as valid in the | |
270 | .I dqi_valid | |
271 | field. | |
272 | The | |
273 | .I id | |
274 | argument is ignored. | |
fea681da | 275 | .TP |
1eeddf25 JK |
276 | .B Q_SETINFO |
277 | Set information about quotafile. | |
278 | The | |
fea681da | 279 | .I addr |
1eeddf25 JK |
280 | argument should be a pointer to a |
281 | .I dqinfo | |
282 | structure. | |
283 | The | |
284 | .I dqi_valid | |
285 | field of the | |
286 | .I dqinfo | |
287 | structure indicates the entries in the structure | |
288 | that have been set by the caller. | |
289 | This operation supersedes the | |
290 | .B Q_SETGRACE | |
291 | and | |
292 | .B Q_SETFLAGS | |
293 | operations in the previous quota interfaces. | |
294 | The | |
295 | .I id | |
296 | argument is ignored. | |
297 | This operation requires privilege | |
298 | .RB ( CAP_SYS_ADMIN ). | |
fea681da | 299 | .TP |
1eeddf25 JK |
300 | .B Q_GETFMT |
301 | Get quota format used on the specified file system. | |
302 | The | |
303 | .I addr | |
304 | argument should be a pointer to a 4-byte buffer | |
305 | where the format number will be stored. | |
fea681da MK |
306 | .TP |
307 | .B Q_SYNC | |
1eeddf25 JK |
308 | Update the on-disk copy of quota usages for a file system. |
309 | If | |
310 | .I special | |
311 | is NULL, then all file systems with active quotas are sync'ed. | |
312 | The | |
313 | .I addr | |
314 | and | |
315 | .I id | |
316 | arguments are ignored. | |
fea681da MK |
317 | .TP |
318 | .B Q_GETSTATS | |
1eeddf25 JK |
319 | Get statistics and other generic information about the quota subsystem. |
320 | The | |
321 | .I addr | |
322 | argument should be a pointer to a | |
323 | .I dqstats | |
324 | structure in which data should be stored. | |
325 | This structure is defined in | |
326 | .IR <sys/quota.h>. | |
327 | The | |
328 | .I special | |
329 | and | |
330 | .I id | |
331 | arguments are ignored. | |
332 | This operation is obsolete and not supported by recent kernels. | |
333 | .\" Q_GETSTATS was removed in kernel 2.4.22. | |
334 | Files in | |
335 | .I /proc/sys/fs/quota/ | |
336 | carry the information instead. | |
337 | .PP | |
338 | For XFS file systems making use of the XFS Quota Manager (XQM), | |
339 | the above commands are bypassed and the following commands are used: | |
340 | .TP 8 | |
341 | .B Q_XQUOTAON | |
342 | Turn on quotas for an XFS file system. | |
343 | XFS provides the ability to turn on/off quota limit enforcement | |
344 | with quota accounting. | |
345 | Therefore, XFS expects | |
346 | .I addr | |
347 | to be a pointer to an | |
348 | .I "unsigned int" | |
349 | that contains either the flags | |
350 | .B XFS_QUOTA_UDQ_ACCT | |
351 | and/or | |
352 | .B XFS_QUOTA_UDQ_ENFD | |
353 | (for user quota), or | |
354 | .B XFS_QUOTA_GDQ_ACCT | |
355 | and/or | |
356 | .B XFS_QUOTA_GDQ_ENFD | |
357 | (for group quota), as defined in | |
358 | .IR <xfs/xqm.h> . | |
359 | This operation requires privilege | |
360 | .RB ( CAP_SYS_ADMIN ). | |
361 | .TP | |
362 | .B Q_XQUOTAOFF | |
363 | Turn off quotas for an XFS file system. | |
364 | As with | |
365 | .BR Q_QUOTAON , | |
366 | XFS file systems expect a pointer to an | |
367 | .I "unsigned int" | |
368 | that specifies whether quota accounting and/or limit enforcement need | |
369 | to be turned off. | |
370 | This operation requires privilege | |
371 | .RB ( CAP_SYS_ADMIN ). | |
372 | .TP | |
373 | .B Q_XGETQUOTA | |
374 | Get disk quota limits and current usage for user | |
375 | .IR id . | |
376 | The | |
377 | .I addr | |
378 | argument is a pointer to an | |
379 | .I fs_disk_quota | |
380 | structure (defined in | |
381 | .IR <xfs/xqm.h> ). | |
382 | Unprivileged users may retrieve only their own quotas; | |
383 | a privileged user | |
384 | .RB ( CAP_SYS_ADMIN ) | |
385 | may retrieve the quotas of any user. | |
386 | .TP | |
387 | .B Q_XSETQLIM | |
388 | Set disk quota limits for user | |
389 | .IR id . | |
390 | The | |
391 | .I addr | |
392 | argument is a pointer to an | |
393 | .I fs_disk_quota | |
394 | structure (defined in | |
395 | .IR <xfs/xqm.h> ). | |
396 | This operation requires privilege | |
397 | .RB ( CAP_SYS_ADMIN ). | |
398 | .TP | |
399 | .B Q_XGETQSTAT | |
400 | Returns an | |
401 | .I fs_quota_stat | |
402 | structure containing XFS file system specific quota information. | |
403 | This is useful for finding out how much space is used to store quota | |
404 | information, and also to get quotaon/off status of a given local XFS | |
405 | file system. | |
406 | .TP | |
407 | .B Q_XQUOTARM | |
408 | Free the disk space taken by disk quotas. | |
409 | Quotas must have already been turned off. | |
410 | .PP | |
411 | There is no command equivalent to | |
412 | .B Q_SYNC | |
413 | for XFS since | |
414 | .BR sync (1) | |
415 | writes quota information to disk (in addition to the other file system | |
416 | metadata that it writes out). | |
417 | .SH RETURN VALUES | |
418 | .LP | |
fea681da | 419 | On success, |
e511ffb6 | 420 | .BR quotactl () |
1eeddf25 JK |
421 | returns 0; on error \-1 |
422 | is returned, and | |
fea681da | 423 | .I errno |
1eeddf25 | 424 | is set to indicate the error. |
fea681da | 425 | .SH ERRORS |
fea681da MK |
426 | .TP |
427 | .B EFAULT | |
fea681da | 428 | .I addr |
1eeddf25 JK |
429 | or |
430 | .I special | |
431 | is invalid. | |
fea681da MK |
432 | .TP |
433 | .B EINVAL | |
1eeddf25 JK |
434 | .I cmd |
435 | or | |
fea681da | 436 | .I type |
1eeddf25 | 437 | is invalid. |
fea681da | 438 | .TP |
1eeddf25 JK |
439 | .B ENOENT |
440 | The file specified by | |
fea681da | 441 | .I special |
1eeddf25 JK |
442 | or |
443 | .I addr | |
444 | does not exist. | |
fea681da | 445 | .TP |
1eeddf25 JK |
446 | .B ENOSYS |
447 | The kernel has not been compiled with the | |
448 | .B CONFIG_QUOTA | |
449 | option. | |
fea681da MK |
450 | .TP |
451 | .B ENOTBLK | |
452 | .I special | |
1eeddf25 | 453 | is not a block device. |
fea681da MK |
454 | .TP |
455 | .B EPERM | |
1eeddf25 JK |
456 | The caller lacked the required privilege |
457 | .RB ( CAP_SYS_ADMIN ) | |
458 | for the specified operation. | |
fea681da MK |
459 | .TP |
460 | .B ESRCH | |
1eeddf25 JK |
461 | No disk quota is found for the indicated user. |
462 | Quotas have not been turned on for this file system. | |
463 | .LP | |
464 | If | |
465 | .I cmd | |
466 | is | |
467 | .BR Q_SETQUOTA , | |
468 | .BR quotactl () | |
469 | may also set | |
470 | .I errno | |
471 | to: | |
472 | .TP | |
473 | .B ERANGE | |
474 | Specified limits are out of range allowed by quota format. | |
475 | .LP | |
476 | If | |
477 | .I cmd | |
478 | is | |
479 | .BR Q_QUOTAON , | |
480 | .BR quotactl () | |
481 | may also set | |
482 | .I errno | |
483 | to: | |
484 | .TP | |
485 | .B EACCES | |
486 | The quota file pointed to by | |
487 | .I addr | |
488 | exists, but is not a regular file; or, | |
489 | the quota file pointed to by | |
490 | .I addr | |
491 | exists, but is not on the file system pointed to by | |
492 | .IR special . | |
493 | .TP | |
494 | .B EBUSY | |
495 | .B Q_QUOTAON | |
496 | attempted, but another | |
497 | .B Q_QUOTAON | |
498 | had already been performed. | |
499 | .TP | |
500 | .B EINVAL | |
501 | The quota file is corrupted. | |
502 | .TP | |
503 | .B ESRCH | |
504 | Specified quota format was not found. | |
fea681da MK |
505 | .SH "SEE ALSO" |
506 | .BR quota (1), | |
507 | .BR getrlimit (2), | |
fea681da MK |
508 | .BR quotacheck (8), |
509 | .BR quotaon (8) |