1QUOTACTL(2) Linux Programmer's Manual QUOTACTL(2)
2
6 quotactl - manipulate disk quotas
7
9 #include <sys/quota.h>
10 #include <xfs/xqm.h> /* for XFS quotas */
11 int quotactl(int cmd, const char *special, int id, caddr_t addr);
13
15 The quota system can be used to set per-user, per-group, and per-
16 project limits on the amount of disk space used on a filesystem. For
17 each user and/or group, a soft limit and a hard limit can be set for
18 each filesystem. The hard limit can't be exceeded. The soft limit can
19 be exceeded, but warnings will ensue. Moreover, the user can't exceed
20 the soft limit for more than grace period duration (one week by
21 default) at a time; after this, the soft limit counts as a hard limit.
22 The quotactl() call manipulates disk quotas. The cmd argument indi‐
24 cates a command to be applied to the user or group ID specified in id.
25 To initialize the cmd argument, use the QCMD(subcmd, type) macro. The
26 type value is either USRQUOTA, for user quotas, GRPQUOTA, for group
27 quotas, or (since Linux 4.1) PRJQUOTA, for project quotas. The subcmd
28 value is described below.
29 The special argument is a pointer to a null-terminated string contain‐
31 ing the pathname of the (mounted) block special device for the filesys‐
32 tem being manipulated.
33 The addr argument is the address of an optional, command-specific, data
35 structure that is copied in or out of the system. The interpretation
36 of addr is given with each command below.
37 The subcmd value is one of the following:
39 Q_QUOTAON
41 Turn on quotas for a filesystem. The id argument is the iden‐
42 tification number of the quota format to be used. Currently,
43 there are three supported quota formats:
44 QFMT_VFS_OLD The original quota format.
46 QFMT_VFS_V0 The standard VFS v0 quota format, which can handle
48 32-bit UIDs and GIDs and quota limits up to 2^42
49 bytes and 2^32 inodes.
50 QFMT_VFS_V1 A quota format that can handle 32-bit UIDs and
52 GIDs and quota limits of 2^64 bytes and 2^64
53 inodes.
54 The addr argument points to the pathname of a file containing
56 the quotas for the filesystem. The quota file must exist; it
57 is normally created with the quotacheck(8) program. This oper‐
58 ation requires privilege (CAP_SYS_ADMIN).
59 Q_QUOTAOFF
61 Turn off quotas for a filesystem. The addr and id arguments
62 are ignored. This operation requires privilege
63 (CAP_SYS_ADMIN).
64 Q_GETQUOTA
66 Get disk quota limits and current usage for user or group id.
67 The addr argument is a pointer to a dqblk structure defined in
68 <sys/quota.h> as follows:
69 /* uint64_t is an unsigned 64-bit integer;
71 uint32_t is an unsigned 32-bit integer */
72 struct dqblk { /* Definition since Linux 2.4.22 */
74 uint64_t dqb_bhardlimit; /* Absolute limit on disk
75 quota blocks alloc */
76 uint64_t dqb_bsoftlimit; /* Preferred limit on
77 disk quota blocks */
78 uint64_t dqb_curspace; /* Current occupied space
79 (in bytes) */
80 uint64_t dqb_ihardlimit; /* Maximum number of
81 allocated inodes */
82 uint64_t dqb_isoftlimit; /* Preferred inode limit */
83 uint64_t dqb_curinodes; /* Current number of
84 allocated inodes */
85 uint64_t dqb_btime; /* Time limit for excessive
86 disk use */
87 uint64_t dqb_itime; /* Time limit for excessive
88 files */
89 uint32_t dqb_valid; /* Bit mask of QIF_*
90 constants */
91 };
92 /* Flags in dqb_valid that indicate which fields in
94 dqblk structure are valid. */
95 #define QIF_BLIMITS 1
97 #define QIF_SPACE 2
98 #define QIF_ILIMITS 4
99 #define QIF_INODES 8
100 #define QIF_BTIME 16
101 #define QIF_ITIME 32
102 #define QIF_LIMITS (QIF_BLIMITS | QIF_ILIMITS)
103 #define QIF_USAGE (QIF_SPACE | QIF_INODES)
104 #define QIF_TIMES (QIF_BTIME | QIF_ITIME)
105 #define QIF_ALL (QIF_LIMITS | QIF_USAGE | QIF_TIMES)
106 The dqb_valid field is a bit mask that is set to indicate the
108 entries in the dqblk structure that are valid. Currently, the
109 kernel fills in all entries of the dqblk structure and marks
110 them as valid in the dqb_valid field. Unprivileged users may
111 retrieve only their own quotas; a privileged user
112 (CAP_SYS_ADMIN) can retrieve the quotas of any user.
113 Q_GETNEXTQUOTA (since Linux 4.6)
115 This operation is the same as Q_GETQUOTA, but it returns quota
116 information for the next ID greater than or equal to id that
117 has a quota set.
118 The addr argument is a pointer to a nextdqblk structure whose
120 fields are as for the dqblk, except for the addition of a
121 dqb_id field that is used to return the ID for which quota
122 information is being returned:
123 struct nextdqblk {
125 uint64_t dqb_bhardlimit;
126 uint64_t dqb_bsoftlimit;
127 uint64_t dqb_curspace;
128 uint64_t dqb_ihardlimit;
129 uint64_t dqb_isoftlimit;
130 uint64_t dqb_curinodes;
131 uint64_t dqb_btime;
132 uint64_t dqb_itime;
133 uint32_t dqb_valid;
134 uint32_t dqb_id;
135 };
136 Q_SETQUOTA
138 Set quota information for user or group id, using the informa‐
139 tion supplied in the dqblk structure pointed to by addr. The
140 dqb_valid field of the dqblk structure indicates which entries
141 in the structure have been set by the caller. This operation
142 supersedes the Q_SETQLIM and Q_SETUSE operations in the previ‐
143 ous quota interfaces. This operation requires privilege
144 (CAP_SYS_ADMIN).
145 Q_GETINFO (since Linux 2.4.22)
147 Get information (like grace times) about quotafile. The addr
148 argument should be a pointer to a dqinfo structure. This
149 structure is defined in <sys/quota.h> as follows:
150 /* uint64_t is an unsigned 64-bit integer;
152 uint32_t is an unsigned 32-bit integer */
153 struct dqinfo { /* Defined since kernel 2.4.22 */
155 uint64_t dqi_bgrace; /* Time before block soft limit
156 becomes hard limit */
157 uint64_t dqi_igrace; /* Time before inode soft limit
158 becomes hard limit */
159 uint32_t dqi_flags; /* Flags for quotafile
160 (DQF_*) */
161 uint32_t dqi_valid;
162 };
163 /* Bits for dqi_flags */
165 /* Quota format QFMT_VFS_OLD */
167 #define DQF_ROOT_SQUASH (1 << 0) /* Root squash enabled */
169 /* Before Linux v4.0, this had been defined
170 privately as V1_DQF_RSQUASH */
171 /* Quota format QFMT_VFS_V0 / QFMT_VFS_V1 */
173 #define DQF_SYS_FILE (1 << 16) /* Quota stored in
175 a system file */
176 /* Flags in dqi_valid that indicate which fields in
178 dqinfo structure are valid. */
179 #define IIF_BGRACE 1
181 #define IIF_IGRACE 2
182 #define IIF_FLAGS 4
183 #define IIF_ALL (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)
184 The dqi_valid field in the dqinfo structure indicates the
186 entries in the structure that are valid. Currently, the kernel
187 fills in all entries of the dqinfo structure and marks them all
188 as valid in the dqi_valid field. The id argument is ignored.
189 Q_SETINFO (since Linux 2.4.22)
191 Set information about quotafile. The addr argument should be a
192 pointer to a dqinfo structure. The dqi_valid field of the
193 dqinfo structure indicates the entries in the structure that
194 have been set by the caller. This operation supersedes the
195 Q_SETGRACE and Q_SETFLAGS operations in the previous quota
196 interfaces. The id argument is ignored. This operation
197 requires privilege (CAP_SYS_ADMIN).
198 Q_GETFMT (since Linux 2.4.22)
200 Get quota format used on the specified filesystem. The addr
201 argument should be a pointer to a 4-byte buffer where the for‐
202 mat number will be stored.
203 Q_SYNC Update the on-disk copy of quota usages for a filesystem. If
205 special is NULL, then all filesystems with active quotas are
206 sync'ed. The addr and id arguments are ignored.
207 Q_GETSTATS (supported up to Linux 2.4.21)
209 Get statistics and other generic information about the quota
210 subsystem. The addr argument should be a pointer to a dqstats
211 structure in which data should be stored. This structure is
212 defined in <sys/quota.h>. The special and id arguments are
213 ignored.
214 This operation is obsolete and was removed in Linux 2.4.22.
216 Files in /proc/sys/fs/quota/ carry the information instead.
217 For XFS filesystems making use of the XFS Quota Manager (XQM), the
219 above commands are bypassed and the following commands are used:
220 Q_XQUOTAON
222 Turn on quotas for an XFS filesystem. XFS provides the ability
223 to turn on/off quota limit enforcement with quota accounting.
224 Therefore, XFS expects addr to be a pointer to an unsigned int
225 that contains a combination of the following flags (defined in
226 <xfs/xqm.h>):
227 #define XFS_QUOTA_UDQ_ACCT (1<<0) /* User quota
229 accounting */
230 #define XFS_QUOTA_UDQ_ENFD (1<<1) /* User quota limits
231 enforcement */
232 #define XFS_QUOTA_GDQ_ACCT (1<<2) /* Group quota
233 accounting */
234 #define XFS_QUOTA_GDQ_ENFD (1<<3) /* Group quota limits
235 enforcement */
236 #define XFS_QUOTA_PDQ_ACCT (1<<4) /* Project quota
237 accounting */
238 #define XFS_QUOTA_PDQ_ENFD (1<<5) /* Project quota limits
239 enforcement */
240 This operation requires privilege (CAP_SYS_ADMIN). The id
242 argument is ignored.
243 Q_XQUOTAOFF
245 Turn off quotas for an XFS filesystem. As with Q_QUOTAON, XFS
246 filesystems expect a pointer to an unsigned int that specifies
247 whether quota accounting and/or limit enforcement need to be
248 turned off (using the same flags as for Q_XQUOTAON subcommand).
249 This operation requires privilege (CAP_SYS_ADMIN). The id
250 argument is ignored.
251 Q_XGETQUOTA
253 Get disk quota limits and current usage for user id. The addr
254 argument is a pointer to an fs_disk_quota structure, which is
255 defined in <xfs/xqm.h> as follows:
256 /* All the blk units are in BBs (Basic Blocks) of
258 512 bytes. */
259 #define FS_DQUOT_VERSION 1 /* fs_disk_quota.d_version */
261 #define XFS_USER_QUOTA (1<<0) /* User quota type */
263 #define XFS_PROJ_QUOTA (1<<1) /* Project quota type */
264 #define XFS_GROUP_QUOTA (1<<2) /* Group quota type */
265 struct fs_disk_quota {
267 int8_t d_version; /* Version of this structure */
268 int8_t d_flags; /* XFS_{USER,PROJ,GROUP}_QUOTA */
269 uint16_t d_fieldmask; /* Field specifier */
270 uint32_t d_id; /* User, project, or group ID */
271 uint64_t d_blk_hardlimit; /* Absolute limit on
272 disk blocks */
273 uint64_t d_blk_softlimit; /* Preferred limit on
274 disk blocks */
275 uint64_t d_ino_hardlimit; /* Maximum # allocated
276 inodes */
277 uint64_t d_ino_softlimit; /* Preferred inode limit */
278 uint64_t d_bcount; /* # disk blocks owned by
279 the user */
280 uint64_t d_icount; /* # inodes owned by the user */
281 int32_t d_itimer; /* Zero if within inode limits */
282 /* If not, we refuse service */
283 int32_t d_btimer; /* Similar to above; for
284 disk blocks */
285 uint16_t d_iwarns; /* # warnings issued with
286 respect to # of inodes */
287 uint16_t d_bwarns; /* # warnings issued with
288 respect to disk blocks */
289 int32_t d_padding2; /* Padding - for future use */
290 uint64_t d_rtb_hardlimit; /* Absolute limit on realtime
291 (RT) disk blocks */
292 uint64_t d_rtb_softlimit; /* Preferred limit on RT
293 disk blocks */
294 uint64_t d_rtbcount; /* # realtime blocks owned */
295 int32_t d_rtbtimer; /* Similar to above; for RT
296 disk blocks */
297 uint16_t d_rtbwarns; /* # warnings issued with
298 respect to RT disk blocks */
299 int16_t d_padding3; /* Padding - for future use */
300 char d_padding4[8]; /* Yet more padding */
301 };
302 Unprivileged users may retrieve only their own quotas; a privi‐
304 leged user (CAP_SYS_ADMIN) may retrieve the quotas of any user.
305 Q_XGETNEXTQUOTA (since Linux 4.6)
307 This operation is the same as Q_XGETQUOTA, but it returns (in
308 the fs_disk_quota structure pointed by addr) quota information
309 for the next ID greater than or equal to id that has a quota
310 set. Note that since fs_disk_quota already has q_id field, no
311 separate structure type is needed (in contrast with Q_GETQUOTA
312 and Q_GETNEXTQUOTA commands)
313 Q_XSETQLIM
315 Set disk quota limits for user id. The addr argument is a
316 pointer to an fs_disk_quota structure. This operation requires
317 privilege (CAP_SYS_ADMIN).
318 Q_XGETQSTAT
320 Returns XFS filesystem-specific quota information in the
321 fs_quota_stat structure pointed by addr. This is useful for
322 finding out how much space is used to store quota information,
323 and also to get the quota on/off status of a given local XFS
324 filesystem. The fs_quota_stat structure itself is defined as
325 follows:
326 #define FS_QSTAT_VERSION 1 /* fs_quota_stat.qs_version */
328 struct fs_qfilestat {
330 uint64_t qfs_ino; /* Inode number */
331 uint64_t qfs_nblks; /* Number of BBs
332 512-byte-blocks */
333 uint32_t qfs_nextents; /* Number of extents */
334 };
335 struct fs_quota_stat {
337 int8_t qs_version; /* Version number for
338 future changes */
339 uint16_t qs_flags; /* XFS_QUOTA_{U,P,G}DQ_{ACCT,ENFD} */
340 int8_t qs_pad; /* Unused */
341 struct fs_qfilestat qs_uquota; /* User quota storage
342 information */
343 struct fs_qfilestat qs_gquota; /* Group quota storage
344 information */
345 uint32_t qs_incoredqs; /* Number of dquots in core */
346 int32_t qs_btimelimit; /* Limit for blocks timer */
347 int32_t qs_itimelimit; /* Limit for inodes timer */
348 int32_t qs_rtbtimelimit;/* Limit for RT
349 blocks timer */
350 uint16_t qs_bwarnlimit; /* Limit for # of warnings */
351 uint16_t qs_iwarnlimit; /* Limit for # of warnings */
352 };
353 The id argument is ignored.
355 Q_XGETQSTATV
357 Returns XFS filesystem-specific quota information in the
358 fs_quota_statv pointed to by addr. This version of the command
359 uses a structure with proper versioning support, along with
360 appropriate layout (all fields are naturally aligned) and pad‐
361 ding to avoiding special compat handling; it also provides the
362 ability to get statistics regarding the project quota file.
363 The fs_quota_statv structure itself is defined as follows:
364 #define FS_QSTATV_VERSION1 1 /* fs_quota_statv.qs_version */
366 struct fs_qfilestatv {
368 uint64_t qfs_ino; /* Inode number */
369 uint64_t qfs_nblks; /* Number of BBs
370 512-byte-blocks */
371 uint32_t qfs_nextents; /* Number of extents */
372 uint32_t qfs_pad; /* Pad for 8-byte alignment */
373 };
374 struct fs_quota_statv {
376 int8_t qs_version; /* Version for future
377 changes */
378 uint8_t qs_pad1; /* Pad for 16-bit alignment */
379 uint16_t qs_flags; /* XFS_QUOTA_.* flags */
380 uint32_t qs_incoredqs; /* Number of dquots incore */
381 struct fs_qfilestatv qs_uquota; /* User quota
382 information */
383 struct fs_qfilestatv qs_gquota; /* Group quota
384 information */
385 struct fs_qfilestatv qs_pquota; /* Project quota
386 information */
387 int32_t qs_btimelimit; /* Limit for blocks timer */
388 int32_t qs_itimelimit; /* Limit for inodes timer */
389 int32_t qs_rtbtimelimit; /* Limit for RT blocks
390 timer */
391 uint16_t qs_bwarnlimit; /* Limit for # of warnings */
392 uint16_t qs_iwarnlimit; /* Limit for # of warnings */
393 uint64_t qs_pad2[8]; /* For future proofing */
394 };
395 The qs_version field of the structure should be filled with the
397 version of the structure supported by the callee (for now, only
398 FS_QSTAT_VERSION1 is supported). The kernel will fill the
399 structure in accordance with version provided. The id argument
400 is ignored.
401 Q_XQUOTARM
403 Free the disk space taken by disk quotas. The addr argument
404 should be a pointer to an unsigned int value containing flags
405 (the same as in d_flags field of fs_disk_quota structure) which
406 identify what types of quota should be removed (note that the
407 quota type passed in the cmd argument is ignored, but should
408 remain valid in order to pass preliminary quotactl syscall han‐
409 dler checks).
410 Quotas must have already been turned off. The id argument is
412 ignored.
413 Q_XQUOTASYNC (since Linux 2.6.15; no-op since Linux 3.4)
415 This command was an XFS quota equivalent to Q_SYNC, but it is
416 no-op since Linux 3.4, as sync(1) writes quota information to
417 disk now (in addition to the other filesystem metadata that it
418 writes out). The special, id and addr arguments are ignored.
419
421 On success, quotactl() returns 0; on error -1 is returned, and errno is
422 set to indicate the error.
423
425 EACCES cmd is Q_QUOTAON, and the quota file pointed to by addr exists,
426 but is not a regular file or is not on the filesystem pointed to
427 by special.
428 EBUSY cmd is Q_QUOTAON, but another Q_QUOTAON had already been per‐
430 formed.
431 EFAULT addr or special is invalid.
433 EINVAL cmd or type is invalid.
435 EINVAL cmd is Q_QUOTAON, but the specified quota file is corrupted.
437 ENOENT The file specified by special or addr does not exist.
439 ENOSYS The kernel has not been compiled with the CONFIG_QUOTA option.
441 ENOTBLK
443 special is not a block device.
444 EPERM The caller lacked the required privilege (CAP_SYS_ADMIN) for the
446 specified operation.
447 ERANGE cmd is Q_SETQUOTA, but the specified limits are out of the range
449 allowed by the quota format.
450 ESRCH No disk quota is found for the indicated user. Quotas have not
452 been turned on for this filesystem.
453 ESRCH cmd is Q_QUOTAON, but the specified quota format was not found.
455 ESRCH cmd is Q_GETNEXTQUOTA or Q_XGETNEXTQUOTA, but there is no ID
457 greater than or equal to id that has an active quota.
458
460 Instead of <xfs/xqm.h> one can use <linux/dqblk_xfs.h>, taking into
461 account that there are several naming discrepancies:
462 · Quota enabling flags (of format XFS_QUOTA_[UGP]DQ_{ACCT,ENFD}) are
464 defined without a leading "X", as FS_QUOTA_[UGP]DQ_{ACCT,ENFD}.
465 · The same is true for XFS_{USER,GROUP,PROJ}_QUOTA quota type flags,
467 which are defined as FS_{USER,GROUP,PROJ}_QUOTA.
468 · The dqblk_xfs.h header file defines its own XQM_USRQUOTA,
470 XQM_GRPQUOTA, and XQM_PRJQUOTA constants for the available quota
471 types, but their values are the same as for constants without the
472 XQM_ prefix.
473
475 quota(1), getrlimit(2), quotacheck(8), quotaon(8)
476
478 This page is part of release 5.02 of the Linux man-pages project. A
479 description of the project, information about reporting bugs, and the
480 latest version of this page, can be found at
481 https://www.kernel.org/doc/man-pages/.
482Linux 2017-09-15 QUOTACTL(2)