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