1QUOTACTL(2)                Linux Programmer's Manual               QUOTACTL(2)
2
3
4

NAME

6       quotactl - manipulate disk quotas
7

SYNOPSIS

9       #include <sys/quota.h>
10       #include <xfs/xqm.h> /* for XFS quotas */
11
12       int quotactl(int cmd, const char *special, int id, caddr_t addr);
13

DESCRIPTION

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
23       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
30       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
34       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 operation below.
37
38       The subcmd value is one of the following operations:
39
40       Q_QUOTAON
41              Turn on quotas for a filesystem.  The id argument is the identi‐
42              fication  number  of  the  quota  format to be used.  Currently,
43              there are three supported quota formats:
44
45              QFMT_VFS_OLD The original quota format.
46
47              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
51              QFMT_VFS_V1  A quota format that can handle 32-bit UIDs and GIDs
52                           and quota limits of 2^64 bytes and 2^64 inodes.
53
54              The  addr  argument  points to the pathname of a file containing
55              the quotas for the filesystem.  The quota file must exist; it is
56              normally created with the quotacheck(8) program
57
58              Quota information can be also stored in hidden system inodes for
59              ext4, XFS, and other filesystems if the filesystem is configured
60              so.  In this case, there are no visible quota files and there is
61              no need to use quotacheck(8).  Quota information is always  kept
62              consistent  by the filesystem and the Q_QUOTAON operation serves
63              only to enable enforcement of quota  limits.   The  presence  of
64              hidden  system inodes with quota information is indicated by the
65              DQF_SYS_FILE flag in the dqi_flags field returned by the  Q_GET‐
66              INFO operation.
67
68              This operation requires privilege (CAP_SYS_ADMIN).
69
70       Q_QUOTAOFF
71              Turn off quotas for a filesystem.  The addr and id arguments are
72              ignored.  This operation requires privilege (CAP_SYS_ADMIN).
73
74       Q_GETQUOTA
75              Get disk quota limits and current usage for user  or  group  id.
76              The  addr  argument is a pointer to a dqblk structure defined in
77              <sys/quota.h> as follows:
78
79                  /* uint64_t is an unsigned 64-bit integer;
80                     uint32_t is an unsigned 32-bit integer */
81
82                  struct dqblk {      /* Definition since Linux 2.4.22 */
83                      uint64_t dqb_bhardlimit;  /* Absolute limit on disk
84                                                   quota blocks alloc */
85                      uint64_t dqb_bsoftlimit;  /* Preferred limit on
86                                                   disk quota blocks */
87                      uint64_t dqb_curspace;    /* Current occupied space
88                                                   (in bytes) */
89                      uint64_t dqb_ihardlimit;  /* Maximum number of
90                                                   allocated inodes */
91                      uint64_t dqb_isoftlimit;  /* Preferred inode limit */
92                      uint64_t dqb_curinodes;   /* Current number of
93                                                   allocated inodes */
94                      uint64_t dqb_btime;       /* Time limit for excessive
95                                                   disk use */
96                      uint64_t dqb_itime;       /* Time limit for excessive
97                                                   files */
98                      uint32_t dqb_valid;       /* Bit mask of QIF_*
99                                                   constants */
100                  };
101
102                  /* Flags in dqb_valid that indicate which fields in
103                     dqblk structure are valid. */
104
105                  #define QIF_BLIMITS   1
106                  #define QIF_SPACE     2
107                  #define QIF_ILIMITS   4
108                  #define QIF_INODES    8
109                  #define QIF_BTIME     16
110                  #define QIF_ITIME     32
111                  #define QIF_LIMITS    (QIF_BLIMITS | QIF_ILIMITS)
112                  #define QIF_USAGE     (QIF_SPACE | QIF_INODES)
113                  #define QIF_TIMES     (QIF_BTIME | QIF_ITIME)
114                  #define QIF_ALL       (QIF_LIMITS | QIF_USAGE | QIF_TIMES)
115
116              The dqb_valid field is a bit mask that is set  to  indicate  the
117              entries  in  the dqblk structure that are valid.  Currently, the
118              kernel fills in all entries of the  dqblk  structure  and  marks
119              them  as  valid  in the dqb_valid field.  Unprivileged users may
120              retrieve   only   their   own   quotas;   a   privileged    user
121              (CAP_SYS_ADMIN) can retrieve the quotas of any user.
122
123       Q_GETNEXTQUOTA (since Linux 4.6)
124              This  operation  is the same as Q_GETQUOTA, but it returns quota
125              information for the next ID greater than or equal to id that has
126              a quota set.
127
128              The  addr  argument  is a pointer to a nextdqblk structure whose
129              fields are as for the dqblk, except for the addition of a dqb_id
130              field  that is used to return the ID for which quota information
131              is being returned:
132
133                  struct nextdqblk {
134                      uint64_t dqb_bhardlimit;
135                      uint64_t dqb_bsoftlimit;
136                      uint64_t dqb_curspace;
137                      uint64_t dqb_ihardlimit;
138                      uint64_t dqb_isoftlimit;
139                      uint64_t dqb_curinodes;
140                      uint64_t dqb_btime;
141                      uint64_t dqb_itime;
142                      uint32_t dqb_valid;
143                      uint32_t dqb_id;
144                  };
145
146       Q_SETQUOTA
147              Set quota information for user or group id, using  the  informa‐
148              tion  supplied  in  the dqblk structure pointed to by addr.  The
149              dqb_valid field of the dqblk structure indicates  which  entries
150              in  the  structure  have been set by the caller.  This operation
151              supersedes the Q_SETQLIM and Q_SETUSE operations in the previous
152              quota    interfaces.     This   operation   requires   privilege
153              (CAP_SYS_ADMIN).
154
155       Q_GETINFO (since Linux 2.4.22)
156              Get information (like grace times) about  quotafile.   The  addr
157              argument should be a pointer to a dqinfo structure.  This struc‐
158              ture is defined in <sys/quota.h> as follows:
159
160                  /* uint64_t is an unsigned 64-bit integer;
161                     uint32_t is an unsigned 32-bit integer */
162
163                  struct dqinfo {         /* Defined since kernel 2.4.22 */
164                      uint64_t dqi_bgrace;  /* Time before block soft limit
165                                               becomes hard limit */
166                      uint64_t dqi_igrace;  /* Time before inode soft limit
167                                               becomes hard limit */
168                      uint32_t dqi_flags;   /* Flags for quotafile
169                                               (DQF_*) */
170                      uint32_t dqi_valid;
171                  };
172
173                  /* Bits for dqi_flags */
174
175                  /* Quota format QFMT_VFS_OLD */
176
177                  #define DQF_ROOT_SQUASH (1 << 0) /* Root squash enabled */
178                                /* Before Linux v4.0, this had been defined
179                                   privately as V1_DQF_RSQUASH */
180
181                  /* Quota format QFMT_VFS_V0 / QFMT_VFS_V1 */
182
183                  #define DQF_SYS_FILE    (1 << 16)   /* Quota stored in
184                                                         a system file */
185
186                  /* Flags in dqi_valid that indicate which fields in
187                     dqinfo structure are valid. */
188
189                  #define IIF_BGRACE  1
190                  #define IIF_IGRACE  2
191                  #define IIF_FLAGS   4
192                  #define IIF_ALL     (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)
193
194              The dqi_valid  field  in  the  dqinfo  structure  indicates  the
195              entries  in the structure that are valid.  Currently, the kernel
196              fills in all entries of the dqinfo structure and marks them  all
197              as valid in the dqi_valid field.  The id argument is ignored.
198
199       Q_SETINFO (since Linux 2.4.22)
200              Set  information about quotafile.  The addr argument should be a
201              pointer to a dqinfo  structure.   The  dqi_valid  field  of  the
202              dqinfo  structure  indicates  the  entries in the structure that
203              have been set by the  caller.   This  operation  supersedes  the
204              Q_SETGRACE  and  Q_SETFLAGS  operations  in  the  previous quota
205              interfaces.   The  id  argument  is  ignored.   This   operation
206              requires privilege (CAP_SYS_ADMIN).
207
208       Q_GETFMT (since Linux 2.4.22)
209              Get  quota  format  used  on the specified filesystem.  The addr
210              argument should be a pointer to a 4-byte buffer where the format
211              number will be stored.
212
213       Q_SYNC Update  the  on-disk  copy of quota usages for a filesystem.  If
214              special is NULL, then all filesystems  with  active  quotas  are
215              sync'ed.  The addr and id arguments are ignored.
216
217       Q_GETSTATS (supported up to Linux 2.4.21)
218              Get  statistics  and  other  generic information about the quota
219              subsystem.  The addr argument should be a pointer to  a  dqstats
220              structure  in  which  data  should be stored.  This structure is
221              defined in <sys/quota.h>.  The  special  and  id  arguments  are
222              ignored.
223
224              This  operation  is  obsolete  and  was removed in Linux 2.4.22.
225              Files in /proc/sys/fs/quota/ carry the information instead.
226
227       For XFS filesystems making use of the  XFS  Quota  Manager  (XQM),  the
228       above operations are bypassed and the following operations are used:
229
230       Q_XQUOTAON
231              Turn  on quotas for an XFS filesystem.  XFS provides the ability
232              to turn on/off quota limit enforcement  with  quota  accounting.
233              Therefore,  XFS  expects addr to be a pointer to an unsigned int
234              that contains a bit-wise  combination  of  the  following  flags
235              (defined in <xfs/xqm.h>):
236
237                  XFS_QUOTA_UDQ_ACCT  /* User quota accounting */
238                  XFS_QUOTA_UDQ_ENFD  /* User quota limits enforcement */
239                  XFS_QUOTA_GDQ_ACCT  /* Group quota accounting */
240                  XFS_QUOTA_GDQ_ENFD  /* Group quota limits enforcement */
241                  XFS_QUOTA_PDQ_ACCT  /* Project quota accounting */
242                  XFS_QUOTA_PDQ_ENFD  /* Project quota limits enforcement */
243
244              This operation requires privilege (CAP_SYS_ADMIN).  The id argu‐
245              ment is ignored.
246
247       Q_XQUOTAOFF
248              Turn off quotas for an XFS filesystem.  As with  Q_QUOTAON,  XFS
249              filesystems  expect  a pointer to an unsigned int that specifies
250              whether quota accounting and/or limit  enforcement  need  to  be
251              turned  off  (using the same flags as for Q_XQUOTAON operation).
252              This operation requires privilege (CAP_SYS_ADMIN).  The id argu‐
253              ment is ignored.
254
255       Q_XGETQUOTA
256              Get  disk  quota limits and current usage for user id.  The addr
257              argument is a pointer to an fs_disk_quota  structure,  which  is
258              defined in <xfs/xqm.h> as follows:
259
260                  /* All the blk units are in BBs (Basic Blocks) of
261                     512 bytes. */
262
263                  #define FS_DQUOT_VERSION  1  /* fs_disk_quota.d_version */
264
265                  #define XFS_USER_QUOTA    (1<<0)  /* User quota type */
266                  #define XFS_PROJ_QUOTA    (1<<1)  /* Project quota type */
267                  #define XFS_GROUP_QUOTA   (1<<2)  /* Group quota type */
268
269                  struct fs_disk_quota {
270                      int8_t   d_version;   /* Version of this structure */
271                      int8_t   d_flags;     /* XFS_{USER,PROJ,GROUP}_QUOTA */
272                      uint16_t d_fieldmask; /* Field specifier */
273                      uint32_t d_id;        /* User, project, or group ID */
274                      uint64_t d_blk_hardlimit; /* Absolute limit on
275                                                   disk blocks */
276                      uint64_t d_blk_softlimit; /* Preferred limit on
277                                                   disk blocks */
278                      uint64_t d_ino_hardlimit; /* Maximum # allocated
279                                                   inodes */
280                      uint64_t d_ino_softlimit; /* Preferred inode limit */
281                      uint64_t d_bcount;    /* # disk blocks owned by
282                                               the user */
283                      uint64_t d_icount;    /* # inodes owned by the user */
284                      int32_t  d_itimer;    /* Zero if within inode limits */
285                                            /* If not, we refuse service */
286                      int32_t  d_btimer;    /* Similar to above; for
287                                               disk blocks */
288                      uint16_t d_iwarns;    /* # warnings issued with
289                                               respect to # of inodes */
290                      uint16_t d_bwarns;    /* # warnings issued with
291                                               respect to disk blocks */
292                      int32_t  d_padding2;  /* Padding - for future use */
293                      uint64_t d_rtb_hardlimit; /* Absolute limit on realtime
294                                                   (RT) disk blocks */
295                      uint64_t d_rtb_softlimit; /* Preferred limit on RT
296                                                   disk blocks */
297                      uint64_t d_rtbcount;  /* # realtime blocks owned */
298                      int32_t  d_rtbtimer;  /* Similar to above; for RT
299                                               disk blocks */
300                      uint16_t d_rtbwarns;  /* # warnings issued with
301                                               respect to RT disk blocks */
302                      int16_t  d_padding3;  /* Padding - for future use */
303                      char     d_padding4[8];   /* Yet more padding */
304                  };
305
306              Unprivileged  users may retrieve only their own quotas; a privi‐
307              leged user (CAP_SYS_ADMIN) may retrieve the quotas of any user.
308
309       Q_XGETNEXTQUOTA (since Linux 4.6)
310              This operation is the same as Q_XGETQUOTA, but  it  returns  (in
311              the  fs_disk_quota  structure pointed by addr) quota information
312              for the next ID greater than or equal to id  that  has  a  quota
313              set.   Note  that since fs_disk_quota already has q_id field, no
314              separate structure type is needed (in contrast  with  Q_GETQUOTA
315              and Q_GETNEXTQUOTA operations)
316
317       Q_XSETQLIM
318              Set  disk  quota  limits  for  user  id.  The addr argument is a
319              pointer to an fs_disk_quota structure.  This operation  requires
320              privilege (CAP_SYS_ADMIN).
321
322       Q_XGETQSTAT
323              Returns   XFS   filesystem-specific  quota  information  in  the
324              fs_quota_stat structure pointed by addr.   This  is  useful  for
325              finding  out  how much space is used to store quota information,
326              and also to get the quota on/off status of  a  given  local  XFS
327              filesystem.   The  fs_quota_stat  structure itself is defined as
328              follows:
329
330                  #define FS_QSTAT_VERSION 1  /* fs_quota_stat.qs_version */
331
332                  struct fs_qfilestat {
333                      uint64_t qfs_ino;       /* Inode number */
334                      uint64_t qfs_nblks;     /* Number of BBs
335                                                 512-byte-blocks */
336                      uint32_t qfs_nextents;  /* Number of extents */
337                  };
338
339                  struct fs_quota_stat {
340                      int8_t   qs_version; /* Version number for
341                                              future changes */
342                      uint16_t qs_flags; /* XFS_QUOTA_{U,P,G}DQ_{ACCT,ENFD} */
343                      int8_t   qs_pad;   /* Unused */
344                      struct fs_qfilestat qs_uquota;  /* User quota storage
345                                                         information */
346                      struct fs_qfilestat qs_gquota;  /* Group quota storage
347                                                         information */
348                      uint32_t qs_incoredqs;   /* Number of dquots in core */
349                      int32_t  qs_btimelimit;  /* Limit for blocks timer */
350                      int32_t  qs_itimelimit;  /* Limit for inodes timer */
351                      int32_t  qs_rtbtimelimit;/* Limit for RT
352                                                  blocks timer */
353                      uint16_t qs_bwarnlimit;  /* Limit for # of warnings */
354                      uint16_t qs_iwarnlimit;  /* Limit for # of warnings */
355                  };
356
357              The id argument is ignored.
358
359       Q_XGETQSTATV
360              Returns  XFS  filesystem-specific  quota  information   in   the
361              fs_quota_statv  pointed  to by addr.  This version of the opera‐
362              tion uses a structure with proper versioning support, along with
363              appropriate  layout  (all fields are naturally aligned) and pad‐
364              ding to avoiding special compat handling; it also  provides  the
365              ability to get statistics regarding the project quota file.  The
366              fs_quota_statv structure itself is defined as follows:
367
368                  #define FS_QSTATV_VERSION1 1 /* fs_quota_statv.qs_version */
369
370                  struct fs_qfilestatv {
371                      uint64_t qfs_ino;       /* Inode number */
372                      uint64_t qfs_nblks;     /* Number of BBs
373                                                 512-byte-blocks */
374                      uint32_t qfs_nextents;  /* Number of extents */
375                      uint32_t qfs_pad;       /* Pad for 8-byte alignment */
376                  };
377
378                  struct fs_quota_statv {
379                      int8_t   qs_version;    /* Version for future
380                                                 changes */
381                      uint8_t  qs_pad1;       /* Pad for 16-bit alignment */
382                      uint16_t qs_flags;      /* XFS_QUOTA_.* flags */
383                      uint32_t qs_incoredqs;  /* Number of dquots incore */
384                      struct fs_qfilestatv qs_uquota;  /* User quota
385                                                          information */
386                      struct fs_qfilestatv qs_gquota;  /* Group quota
387                                                          information */
388                      struct fs_qfilestatv qs_pquota;  /* Project quota
389                                                          information */
390                      int32_t  qs_btimelimit;   /* Limit for blocks timer */
391                      int32_t  qs_itimelimit;   /* Limit for inodes timer */
392                      int32_t  qs_rtbtimelimit; /* Limit for RT blocks
393                                                   timer */
394                      uint16_t qs_bwarnlimit;   /* Limit for # of warnings */
395                      uint16_t qs_iwarnlimit;   /* Limit for # of warnings */
396                      uint64_t qs_pad2[8];      /* For future proofing */
397                  };
398
399              The qs_version field of the structure should be filled with  the
400              version  of the structure supported by the callee (for now, only
401              FS_QSTAT_VERSION1 is  supported).   The  kernel  will  fill  the
402              structure  in accordance with version provided.  The id argument
403              is ignored.
404
405       Q_XQUOTARM  (since Linux 3.16)
406              Free the disk space taken by disk  quotas.   The  addr  argument
407              should  be  a  pointer to an unsigned int value containing flags
408              (the same as in d_flags field of fs_disk_quota structure)  which
409              identify  what types of quota should be removed.  (Note that the
410              quota type passed in the cmd argument  is  ignored,  but  should
411              remain  valid in order to pass preliminary quotactl syscall han‐
412              dler checks.)
413
414              Quotas must have already been turned off.  The  id  argument  is
415              ignored.
416
417       Q_XQUOTASYNC (since Linux 2.6.15; no-op since Linux 3.4)
418              This  operation was an XFS quota equivalent to Q_SYNC, but it is
419              no-op since Linux 3.4, as sync(1) writes  quota  information  to
420              disk  now  (in addition to the other filesystem metadata that it
421              writes out).  The special, id and addr arguments are ignored.
422

RETURN VALUE

424       On success, quotactl() returns 0; on error -1 is returned, and errno is
425       set to indicate the error.
426

ERRORS

428       EACCES cmd  is Q_QUOTAON, and the quota file pointed to by addr exists,
429              but is not a regular file or is not on the filesystem pointed to
430              by special.
431
432       EBUSY  cmd  is  Q_QUOTAON,  but another Q_QUOTAON had already been per‐
433              formed.
434
435       EFAULT addr or special is invalid.
436
437       EINVAL cmd or type is invalid.
438
439       EINVAL cmd is Q_QUOTAON, but the specified quota file is corrupted.
440
441       EINVAL (since Linux 5.5)
442              cmd is Q_XQUOTARM, but addr does not point to valid quota types.
443
444       ENOENT The file specified by special or addr does not exist.
445
446       ENOSYS The kernel has not been compiled with the CONFIG_QUOTA option.
447
448       ENOTBLK
449              special is not a block device.
450
451       EPERM  The caller lacked the required privilege (CAP_SYS_ADMIN) for the
452              specified operation.
453
454       ERANGE cmd is Q_SETQUOTA, but the specified limits are out of the range
455              allowed by the quota format.
456
457       ESRCH  No disk quota is found for the indicated user.  Quotas have  not
458              been turned on for this filesystem.
459
460       ESRCH  cmd is Q_QUOTAON, but the specified quota format was not found.
461
462       ESRCH  cmd  is  Q_GETNEXTQUOTA  or  Q_XGETNEXTQUOTA, but there is no ID
463              greater than or equal to id that has an active quota.
464

NOTES

466       Instead of <xfs/xqm.h> one can  use  <linux/dqblk_xfs.h>,  taking  into
467       account that there are several naming discrepancies:
468
469       ·  Quota  enabling  flags (of format XFS_QUOTA_[UGP]DQ_{ACCT,ENFD}) are
470          defined without a leading "X", as FS_QUOTA_[UGP]DQ_{ACCT,ENFD}.
471
472       ·  The same is true for XFS_{USER,GROUP,PROJ}_QUOTA quota  type  flags,
473          which are defined as FS_{USER,GROUP,PROJ}_QUOTA.
474
475       ·  The   dqblk_xfs.h   header   file   defines  its  own  XQM_USRQUOTA,
476          XQM_GRPQUOTA, and XQM_PRJQUOTA constants  for  the  available  quota
477          types,  but  their  values are the same as for constants without the
478          XQM_ prefix.
479

SEE ALSO

481       quota(1), getrlimit(2), quotacheck(8), quotaon(8)
482

COLOPHON

484       This page is part of release 5.07 of the Linux  man-pages  project.   A
485       description  of  the project, information about reporting bugs, and the
486       latest    version    of    this    page,    can     be     found     at
487       https://www.kernel.org/doc/man-pages/.
488
489
490
491Linux                             2020-04-11                       QUOTACTL(2)
Impressum