original/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 2010-06-16 "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 quota block
 154                                   count */
 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 .B Q_SETQUOTA
 200 Set quota information for user or group
 201 .IR id ,
 202 using the information supplied in the
 203 .I dqblk
 204 structure pointed to by
 205 .IR addr .
 206 The
 207 .I dqb_valid
 208 field of the
 209 .I dqblk
 210 structure indicates which entries in the structure have been set by the caller.
 211 This operation supersedes the
 212 .B Q_SETQLIM
 213 and
 214 .B Q_SETUSE
 215 operations in the previous quota interfaces.
 216 This operation requires privilege
 217 .RB ( CAP_SYS_ADMIN ).
 218 .TP
 219 .B Q_GETINFO
 220 Get information (like grace times) about quotafile.
 221 The
 222 .I addr
 223 argument should be a pointer to a
 224 .I dqinfo
 225 structure.
 226 This structure is defined in
 227 .IR <sys/quota.h>
 228 as follows:
 229 .in +4n
 230 .nf
 231
 232 /* uint64_t is an unsigned 64\-bit integer;
 233    uint32_t is an unsigned 32\-bit integer */
 234
 235 struct dqinfo {         /* Defined since kernel 2.4.22 */
 236     uint64_t dqi_bgrace;    /* Time before block soft limit
 237                                becomes hard limit */
 238
 239     uint64_t dqi_igrace;    /* Time before inode soft limit
 240                                becomes hard limit */
 241     uint32_t dqi_flags;     /* Flags for quotafile
 242                                (DQF_*) */
 243     uint32_t dqi_valid;
 244 };
 245
 246 /* Bits for dqi_flags */
 247
 248 /* Quota format QFMT_VFS_OLD */
 249
 250 #define V1_DQF_RSQUASH  1   /* Root squash enabled */
 251
 252 /* Other quota formats have no dqi_flags bits defined */
 253
 254 /* Flags in dqi_valid that indicate which fields in
 255    dqinfo structure are valid. */
 256
 257 # define IIF_BGRACE     1
 258 # define IIF_IGRACE     2
 259 # define IIF_FLAGS      4
 260 # define IIF_ALL        (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)
 261
 262 .fi
 263 .in
 264 The
 265 .I dqi_valid
 266 field in the
 267 .I dqinfo
 268 structure indicates the entries in the structure that are valid.
 269 Currently, the kernel fills in all entries of the
 270 .I dqinfo
 271 structure and marks them all as valid in the
 272 .I dqi_valid
 273 field.
 274 The
 275 .I id
 276 argument is ignored.
 277 .TP
 278 .B Q_SETINFO
 279 Set information about quotafile.
 280 The
 281 .I addr
 282 argument should be a pointer to a
 283 .I dqinfo
 284 structure.
 285 The
 286 .I dqi_valid
 287 field of the
 288 .I dqinfo
 289 structure indicates the entries in the structure
 290 that have been set by the caller.
 291 This operation supersedes the
 292 .B Q_SETGRACE
 293 and
 294 .B Q_SETFLAGS
 295 operations in the previous quota interfaces.
 296 The
 297 .I id
 298 argument is ignored.
 299 This operation requires privilege
 300 .RB ( CAP_SYS_ADMIN ).
 301 .TP
 302 .B Q_GETFMT
 303 Get quota format used on the specified filesystem.
 304 The
 305 .I addr
 306 argument should be a pointer to a 4-byte buffer
 307 where the format number will be stored.
 308 .TP
 309 .B Q_SYNC
 310 Update the on-disk copy of quota usages for a filesystem.
 311 If
 312 .I special
 313 is NULL, then all filesystems with active quotas are sync'ed.
 314 The
 315 .I addr
 316 and
 317 .I id
 318 arguments are ignored.
 319 .TP
 320 .B Q_GETSTATS
 321 Get statistics and other generic information about the quota subsystem.
 322 The
 323 .I addr
 324 argument should be a pointer to a
 325 .I dqstats
 326 structure in which data should be stored.
 327 This structure is defined in
 328 .IR <sys/quota.h> .
 329 The
 330 .I special
 331 and
 332 .I id
 333 arguments are ignored.
 334 This operation is obsolete and not supported by recent kernels.
 335 .\" Q_GETSTATS was removed in kernel 2.4.22.
 336 Files in
 337 .I /proc/sys/fs/quota/
 338 carry the information instead.
 339 .PP
 340 For XFS filesystems making use of the XFS Quota Manager (XQM),
 341 the above commands are bypassed and the following commands are used:
 342 .TP 8
 343 .B Q_XQUOTAON
 344 Turn on quotas for an XFS filesystem.
 345 XFS provides the ability to turn on/off quota limit enforcement
 346 with quota accounting.
 347 Therefore, XFS expects
 348 .I addr
 349 to be a pointer to an
 350 .I "unsigned int"
 351 that contains either the flags
 352 .B XFS_QUOTA_UDQ_ACCT
 353 and/or
 354 .B XFS_QUOTA_UDQ_ENFD
 355 (for user quota), or
 356 .B XFS_QUOTA_GDQ_ACCT
 357 and/or
 358 .B XFS_QUOTA_GDQ_ENFD
 359 (for group quota), as defined in
 360 .IR <xfs/xqm.h> .
 361 This operation requires privilege
 362 .RB ( CAP_SYS_ADMIN ).
 363 .TP
 364 .B Q_XQUOTAOFF
 365 Turn off quotas for an XFS filesystem.
 366 As with
 367 .BR Q_QUOTAON ,
 368 XFS filesystems expect a pointer to an
 369 .I "unsigned int"
 370 that specifies whether quota accounting and/or limit enforcement need
 371 to be turned off.
 372 This operation requires privilege
 373 .RB ( CAP_SYS_ADMIN ).
 374 .TP
 375 .B Q_XGETQUOTA
 376 Get disk quota limits and current usage for user
 377 .IR id .
 378 The
 379 .I addr
 380 argument is a pointer to an
 381 .I fs_disk_quota
 382 structure (defined in
 383 .IR <xfs/xqm.h> ).
 384 Unprivileged users may retrieve only their own quotas;
 385 a privileged user
 386 .RB ( CAP_SYS_ADMIN )
 387 may retrieve the quotas of any user.
 388 .TP
 389 .B Q_XSETQLIM
 390 Set disk quota limits for user
 391 .IR id .
 392 The
 393 .I addr
 394 argument is a pointer to an
 395 .I fs_disk_quota
 396 structure (defined in
 397 .IR <xfs/xqm.h> ).
 398 This operation requires privilege
 399 .RB ( CAP_SYS_ADMIN ).
 400 .TP
 401 .B Q_XGETQSTAT
 402 Returns an
 403 .I fs_quota_stat
 404 structure containing XFS filesystem-specific quota information.
 405 This is useful for finding out how much space is used to store quota
 406 information, and also to get quotaon/off status of a given local XFS
 407 filesystem.
 408 .TP
 409 .B Q_XQUOTARM
 410 Free the disk space taken by disk quotas.
 411 Quotas must have already been turned off.
 412 .PP
 413 There is no command equivalent to
 414 .B Q_SYNC
 415 for XFS since
 416 .BR sync (1)
 417 writes quota information to disk (in addition to the other filesystem
 418 metadata that it writes out).
 419 .SH RETURN VALUE
 420 .LP
 421 On success,
 422 .BR quotactl ()
 423 returns 0; on error \-1
 424 is returned, and
 425 .I errno
 426 is set to indicate the error.
 427 .SH ERRORS
 428 .TP
 429 .B EFAULT
 430 .I addr
 431 or
 432 .I special
 433 is invalid.
 434 .TP
 435 .B EINVAL
 436 .I cmd
 437 or
 438 .I type
 439 is invalid.
 440 .TP
 441 .B ENOENT
 442 The file specified by
 443 .I special
 444 or
 445 .I addr
 446 does not exist.
 447 .TP
 448 .B ENOSYS
 449 The kernel has not been compiled with the
 450 .B CONFIG_QUOTA
 451 option.
 452 .TP
 453 .B ENOTBLK
 454 .I special
 455 is not a block device.
 456 .TP
 457 .B EPERM
 458 The caller lacked the required privilege
 459 .RB ( CAP_SYS_ADMIN )
 460 for the specified operation.
 461 .TP
 462 .B ESRCH
 463 No disk quota is found for the indicated user.
 464 Quotas have not been turned on for this filesystem.
 465 .LP
 466 If
 467 .I cmd
 468 is
 469 .BR Q_SETQUOTA ,
 470 .BR quotactl ()
 471 may also set
 472 .I errno
 473 to:
 474 .TP
 475 .B ERANGE
 476 Specified limits are out of range allowed by quota format.
 477 .LP
 478 If
 479 .I cmd
 480 is
 481 .BR Q_QUOTAON ,
 482 .BR quotactl ()
 483 may also set
 484 .I errno
 485 to:
 486 .TP
 487 .B EACCES
 488 The quota file pointed to by
 489 .I addr
 490 exists, but is not a regular file; or,
 491 the quota file pointed to by
 492 .I addr
 493 exists, but is not on the filesystem pointed to by
 494 .IR special .
 495 .TP
 496 .B EBUSY
 497 .B Q_QUOTAON
 498 attempted, but another
 499 .B Q_QUOTAON
 500 had already been performed.
 501 .TP
 502 .B EINVAL
 503 The quota file is corrupted.
 504 .TP
 505 .B ESRCH
 506 Specified quota format was not found.
 507 .SH SEE ALSO
 508 .BR quota (1),
 509 .BR getrlimit (2),
 510 .BR quotacheck (8),
 511 .BR quotaon (8)
 512 .SH COLOPHON
 513 This page is part of release 3.79 of the Linux
 514 .I man-pages
 515 project.
 516 A description of the project,
 517 information about reporting bugs,
 518 and the latest version of this page,
 519 can be found at
 520 \%http://www.kernel.org/doc/man\-pages/.