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 command below.
37
38       The subcmd value is one of the following:
39
40       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
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
52                            GIDs  and  quota  limits  of  2^64  bytes and 2^64
53                            inodes.
54
55               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
60       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
65       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
70                   /* uint64_t is an unsigned 64-bit integer;
71                      uint32_t is an unsigned 32-bit integer */
72
73                   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
93                   /* Flags in dqb_valid that indicate which fields in
94                      dqblk structure are valid. */
95
96                   #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
107               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
114       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
119               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
124                   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
137       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
146       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
151                   /* uint64_t is an unsigned 64-bit integer;
152                      uint32_t is an unsigned 32-bit integer */
153
154                   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
164                   /* Bits for dqi_flags */
165
166                   /* Quota format QFMT_VFS_OLD */
167
168                   #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
172                   /* Quota format QFMT_VFS_V0 / QFMT_VFS_V1 */
173
174                   #define DQF_SYS_FILE    (1 << 16)   /* Quota stored in
175                                                          a system file */
176
177                   /* Flags in dqi_valid that indicate which fields in
178                      dqinfo structure are valid. */
179
180                   #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
185               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
190       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
199       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
204       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
208       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
215               This operation is obsolete and was  removed  in  Linux  2.4.22.
216               Files in /proc/sys/fs/quota/ carry the information instead.
217
218       For  XFS  filesystems  making  use  of the XFS Quota Manager (XQM), the
219       above commands are bypassed and the following commands are used:
220
221       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
228                   #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
241               This operation  requires  privilege  (CAP_SYS_ADMIN).   The  id
242               argument is ignored.
243
244       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
252       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
257                   /* All the blk units are in BBs (Basic Blocks) of
258                      512 bytes. */
259
260                   #define FS_DQUOT_VERSION  1  /* fs_disk_quota.d_version */
261
262                   #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
266                   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
303               Unprivileged users may retrieve only their own quotas; a privi‐
304               leged user (CAP_SYS_ADMIN) may retrieve the quotas of any user.
305
306       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
314       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
319       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
327                   #define FS_QSTAT_VERSION 1  /* fs_quota_stat.qs_version */
328
329                   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
336                   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
354               The id argument is ignored.
355
356       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
365                   #define FS_QSTATV_VERSION1 1 /* fs_quota_statv.qs_version */
366
367                   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
375                   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
396               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
402       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
411               Quotas  must  have already been turned off.  The id argument is
412               ignored.
413
414       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

RETURN VALUE

421       On success, quotactl() returns 0; on error -1 is returned, and errno is
422       set to indicate the error.
423

ERRORS

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
429       EBUSY  cmd is Q_QUOTAON, but another Q_QUOTAON had  already  been  per‐
430              formed.
431
432       EFAULT addr or special is invalid.
433
434       EINVAL cmd or type is invalid.
435
436       EINVAL cmd is Q_QUOTAON, but the specified quota file is corrupted.
437
438       ENOENT The file specified by special or addr does not exist.
439
440       ENOSYS The kernel has not been compiled with the CONFIG_QUOTA option.
441
442       ENOTBLK
443              special is not a block device.
444
445       EPERM  The caller lacked the required privilege (CAP_SYS_ADMIN) for the
446              specified operation.
447
448       ERANGE cmd is Q_SETQUOTA, but the specified limits are out of the range
449              allowed by the quota format.
450
451       ESRCH  No  disk quota is found for the indicated user.  Quotas have not
452              been turned on for this filesystem.
453
454       ESRCH  cmd is Q_QUOTAON, but the specified quota format was not found.
455
456       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

NOTES

460       Instead  of  <xfs/xqm.h>  one  can use <linux/dqblk_xfs.h>, taking into
461       account that there are several naming discrepancies:
462
463       ·  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
466       ·  The  same  is true for XFS_{USER,GROUP,PROJ}_QUOTA quota type flags,
467          which are defined as FS_{USER,GROUP,PROJ}_QUOTA.
468
469       ·  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

SEE ALSO

475       quota(1), getrlimit(2), quotacheck(8), quotaon(8)
476

COLOPHON

478       This  page  is  part of release 4.16 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/.
482
483
484
485Linux                             2017-09-15                       QUOTACTL(2)
Impressum