man2/quotactl.2

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