From 093b6f20262a7c0013d1802f7f122ffdcc1dbff5 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 21 Sep 2016 15:40:56 +0200 Subject: [PATCH] quotactl.2: Tweaks to Eugene Syromyatnikov's patches Signed-off-by: Michael Kerrisk --- man2/quotactl.2 | 215 ++++++++++++++++++++++++++++-------------------- 1 file changed, 124 insertions(+), 91 deletions(-) diff --git a/man2/quotactl.2 b/man2/quotactl.2 index 50ce29e81..280e39c70 100644 --- a/man2/quotactl.2 +++ b/man2/quotactl.2 @@ -37,7 +37,7 @@ quotactl \- manipulate disk quotas .fi .SH DESCRIPTION .LP -The quota system can be used to set per-user, per-group and per-project limits +The quota system can be used to set per-user, per-group, and per-project limits on the amount of disk space used on a filesystem. For each user and/or group, a soft limit and a hard limit can be set for each filesystem. @@ -285,19 +285,21 @@ struct dqinfo { /* Defined since kernel 2.4.22 */ /* Quota format QFMT_VFS_OLD */ -/* Before v4.0-rc1~141^2~14 it had been defined privately as V1_DQF_RSQUASH */ -#define DQF_ROOT_SQUASH (1 << 0) /* Root squash enabled */ +#define DQF_ROOT_SQUASH (1 << 0) /* Root squash enabled */ + /* Before Linux v4.0, this had been defined + privately as V1_DQF_RSQUASH */ /* Quota format QFMT_VFS_V0 / QFMT_VFS_V1 */ -#define DQF_SYS_FILE (1 << 16) /* Quota stored in a system file */ +#define DQF_SYS_FILE (1 << 16) /* Quota stored in + a system file */ /* Flags in dqi_valid that indicate which fields in dqinfo structure are valid. */ -# define IIF_BGRACE 1 -# define IIF_IGRACE 2 -# define IIF_FLAGS 4 +# define IIF_BGRACE 1 +# define IIF_IGRACE 2 +# define IIF_FLAGS 4 # define IIF_ALL (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS) .fi @@ -389,17 +391,21 @@ Therefore, XFS expects .I addr to be a pointer to an .I "unsigned int" -that contains the combination of the following flags (defined in +that contains a combination of the following flags (defined in .IR ): .nf .in +4n -#define XFS_QUOTA_UDQ_ACCT (1<<0) /* user quota accounting */ -#define XFS_QUOTA_UDQ_ENFD (1<<1) /* user quota limits enforcement */ -#define XFS_QUOTA_GDQ_ACCT (1<<2) /* group quota accounting */ -#define XFS_QUOTA_GDQ_ENFD (1<<3) /* group quota limits enforcement */ -#define XFS_QUOTA_PDQ_ACCT (1<<4) /* project quota accounting */ -#define XFS_QUOTA_PDQ_ENFD (1<<5) /* project quota limits enforcement */ +#define XFS_QUOTA_UDQ_ACCT (1<<0) /* User quota accounting */ +#define XFS_QUOTA_UDQ_ENFD (1<<1) /* User quota limits + enforcement */ +#define XFS_QUOTA_GDQ_ACCT (1<<2) /* Group quota accounting */ +#define XFS_QUOTA_GDQ_ENFD (1<<3) /* Group quota limits + enforcement */ +#define XFS_QUOTA_PDQ_ACCT (1<<4) /* Project quota + accounting */ +#define XFS_QUOTA_PDQ_ENFD (1<<5) /* Project quota limits + enforcement */ .in .fi @@ -417,7 +423,7 @@ XFS filesystems expect a pointer to an .I "unsigned int" that specifies whether quota accounting and/or limit enforcement need to be turned off (using the same flags as for -.RB Q_XQUOTAON +.B Q_XQUOTAON subcommand). This operation requires privilege .RB ( CAP_SYS_ADMIN ). @@ -432,44 +438,56 @@ The .I addr argument is a pointer to an .I fs_disk_quota -structure which is defined in +structure, which is defined in .I as follows: .nf .in +4n -/* All the blk units are in BBs (Basic Blocks) of 512 bytes. */ +/* All the blk units are in BBs (Basic Blocks) of + 512 bytes. */ -#define FS_DQUOT_VERSION 1 /* fs_disk_quota.d_version */ +#define FS_DQUOT_VERSION 1 /* fs_disk_quota.d_version */ -#define XFS_USER_QUOTA (1<<0) /* user quota type */ -#define XFS_PROJ_QUOTA (1<<1) /* project quota type */ -#define XFS_GROUP_QUOTA (1<<2) /* group quota type */ +#define XFS_USER_QUOTA (1<<0) /* User quota type */ +#define XFS_PROJ_QUOTA (1<<1) /* Project quota type */ +#define XFS_GROUP_QUOTA (1<<2) /* Group quota type */ struct fs_disk_quota { - int8_t d_version; /* version of this structure */ - int8_t d_flags; /* XFS_{USER,PROJ,GROUP}_QUOTA */ - uint16_t d_fieldmask; /* field specifier */ - uint32_t d_id; /* user, project, or group ID */ - uint64_t d_blk_hardlimit; /* absolute limit on disk blks */ - uint64_t d_blk_softlimit; /* preferred limit on disk blks */ - uint64_t d_ino_hardlimit; /* maximum # allocated inodes */ - uint64_t d_ino_softlimit; /* preferred inode limit */ - uint64_t d_bcount; /* # disk blocks owned by the user */ - uint64_t d_icount; /* # inodes owned by the user */ - int32_t d_itimer; /* zero if within inode limits */ - /* if not, we refuse service */ - int32_t d_btimer; /* similar to above; for disk blocks */ - uint16_t d_iwarns; /* # warnings issued wrt num inodes */ - uint16_t d_bwarns; /* # warnings issued wrt disk blocks */ - int32_t d_padding2; /* padding2 - for future use */ - uint64_t d_rtb_hardlimit; /* absolute limit on realtime blks */ - uint64_t d_rtb_softlimit; /* preferred limit on RT disk blks */ - uint64_t d_rtbcount; /* # realtime blocks owned */ - int32_t d_rtbtimer; /* similar to above; for RT disk blks */ - uint16_t d_rtbwarns; /* # warnings issued wrt RT disk blks */ - int16_t d_padding3; /* padding3 - for future use */ - char d_padding4[8]; /* yet more padding */ + int8_t d_version; /* Version of this structure */ + int8_t d_flags; /* XFS_{USER,PROJ,GROUP}_QUOTA */ + uint16_t d_fieldmask; /* Field specifier */ + uint32_t d_id; /* User, project, or group ID */ + uint64_t d_blk_hardlimit; /* Absolute limit on + disk blocks */ + uint64_t d_blk_softlimit; /* Preferred limit on + disk blocks */ + uint64_t d_ino_hardlimit; /* Maximum # allocated + inodes */ + uint64_t d_ino_softlimit; /* Preferred inode limit */ + uint64_t d_bcount; /* # disk blocks owned by + the user */ + uint64_t d_icount; /* # inodes owned by the user */ + int32_t d_itimer; /* Zero if within inode limits */ + /* If not, we refuse service */ + int32_t d_btimer; /* Similar to above; for + disk blocks */ + uint16_t d_iwarns; /* # warnings issued with + respect to # of inodes */ + uint16_t d_bwarns; /* # warnings issued with + respect to disk blocks */ + int32_t d_padding2; /* Padding - for future use */ + uint64_t d_rtb_hardlimit; /* Absolute limit on realtime + (RT) disk blocks */ + uint64_t d_rtb_softlimit; /* Preferred limit on RT + disk blocks */ + uint64_t d_rtbcount; /* # realtime blocks owned */ + int32_t d_rtbtimer; /* Similar to above; for RT + disk blocks */ + uint16_t d_rtbwarns; /* # warnings issued with + respect to RT disk blocks */ + int16_t d_padding3; /* Padding - for future use */ + char d_padding4[8];/* Yet more padding */ }; .in .fi @@ -489,7 +507,8 @@ structure pointed by .IR addr ) quota information for the next ID greater than or equal to .IR id -that has a quota set. Note that since +that has a quota set. +Note that since .I fs_disk_quota already has .I q_id @@ -517,8 +536,9 @@ an .I fs_quota_stat structure containing XFS filesystem-specific quota information. This is useful for finding out how much space is used to store quota -information, and also to get quotaon/off status of a given local XFS -filesystem. The +information, and also to get the quota on/off status of a given local XFS +filesystem. +The .I fs_quota_stat structure itself is defined as follows: @@ -527,23 +547,27 @@ structure itself is defined as follows: #define FS_QSTAT_VERSION 1 /* fs_quota_stat.qs_version */ struct fs_qfilestat { - uint64_t qfs_ino; /* inode number */ - uint64_t qfs_nblks; /* number of BBs 512-byte-blks */ - uint32_t qfs_nextents; /* number of extents */ + uint64_t qfs_ino; /* Inode number */ + uint64_t qfs_nblks; /* Number of BBs + 512-byte-blocks */ + uint32_t qfs_nextents; /* Number of extents */ }; struct fs_quota_stat { - int8_t qs_version; /* version number for future changes */ - uint16_t qs_flags; /* XFS_QUOTA_{U,P,G}DQ_{ACCT,ENFD} */ - int8_t qs_pad; /* unused */ - struct fs_qfilestat qs_uquota; /* user quota storage information */ - struct fs_qfilestat qs_gquota; /* group quota storage information */ - uint32_t qs_incoredqs; /* number of dquots incore */ - int32_t qs_btimelimit; /* limit for blks timer */ - int32_t qs_itimelimit; /* limit for inodes timer */ - int32_t qs_rtbtimelimit; /* limit for rt blks timer */ - uint16_t qs_bwarnlimit; /* limit for num warnings */ - uint16_t qs_iwarnlimit; /* limit for num warnings */ + int8_t qs_version; /* Version number for + future changes */ + uint16_t qs_flags; /* XFS_QUOTA_{U,P,G}DQ_{ACCT,ENFD} */ + int8_t qs_pad; /* Unused */ + struct fs_qfilestat qs_uquota; /* User quota storage + information */ + struct fs_qfilestat qs_gquota; /* Group quota storage + information */ + uint32_t qs_incoredqs; /* Number of dquots in core */ + int32_t qs_btimelimit; /* Limit for blocks timer */ + int32_t qs_itimelimit; /* Limit for inodes timer */ + int32_t qs_rtbtimelimit; /* Limit for RT blocks timer */ + uint16_t qs_bwarnlimit; /* Limit for # of warnings */ + uint16_t qs_iwarnlimit; /* Limit for # of warnings */ }; .in .fi @@ -557,11 +581,13 @@ Returns (in a buffer pointed by .IR addr ) an .I fs_quota_statv -structure containing XFS filesystem-specific quota information. This version -of the command use structure with proper versioning support along with -appropriate layout (all fields are naturally aligned) and adding for avoiding -special compat handling; it also provides ability to get statistics regarding -project quota file. The +structure containing XFS filesystem-specific quota information. +This version of the command uses a structure with proper versioning support, +along with appropriate layout (all fields are naturally aligned) and +padding to avoiding special compat handling; +it also provides the ability to get statistics regarding +the project quota file. +The .I fs_quota_statv structure itself is defined as follows: @@ -570,26 +596,31 @@ structure itself is defined as follows: #define FS_QSTATV_VERSION1 1 /* fs_quota_statv.qs_version */ struct fs_qfilestatv { - uint64_t qfs_ino; /* inode number */ - uint64_t qfs_nblks; /* number of BBs 512-byte-blks */ - uint32_t qfs_nextents; /* number of extents */ - uint32_t qfs_pad; /* pad for 8-byte alignment */ + uint64_t qfs_ino; /* Inode number */ + uint64_t qfs_nblks; /* Number of BBs + 512-byte-blocks */ + uint32_t qfs_nextents; /* Number of extents */ + uint32_t qfs_pad; /* Pad for 8-byte alignment */ }; struct fs_quota_statv { - int8_t qs_version; /* version for future changes */ - uint8_t qs_pad1; /* pad for 16bit alignment */ - uint16_t qs_flags; /* XFS_QUOTA_.* flags */ - uint32_t qs_incoredqs; /* number of dquots incore */ - struct fs_qfilestatv qs_uquota; /* user quota information */ - struct fs_qfilestatv qs_gquota; /* group quota information */ - struct fs_qfilestatv qs_pquota; /* project quota information */ - int32_t qs_btimelimit; /* limit for blks timer */ - int32_t qs_itimelimit; /* limit for inodes timer */ - int32_t qs_rtbtimelimit; /* limit for rt blks timer */ - uint16_t qs_bwarnlimit; /* limit for num warnings */ - uint16_t qs_iwarnlimit; /* limit for num warnings */ - uint64_t qs_pad2[8]; /* for future proofing */ + int8_t qs_version; /* Version for future + changes */ + uint8_t qs_pad1; /* Pad for 16-bit alignment */ + uint16_t qs_flags; /* XFS_QUOTA_.* flags */ + uint32_t qs_incoredqs; /* Number of dquots incore */ + struct fs_qfilestatv qs_uquota; /* User quota + information */ + struct fs_qfilestatv qs_gquota; /* Group quota + information */ + struct fs_qfilestatv qs_pquota; /* Project quota + information */ + int32_t qs_btimelimit; /* Limit for blocks timer */ + int32_t qs_itimelimit; /* Limit for inodes timer */ + int32_t qs_rtbtimelimit; /* Limit for RT blocks timer */ + uint16_t qs_bwarnlimit; /* Limit for # of warnings */ + uint16_t qs_iwarnlimit; /* Limit for # of warnings */ + uint64_t qs_pad2[8]; /* For future proofing */ }; .in .fi @@ -599,7 +630,8 @@ The field of the structure should be filled with the version of the structure supported by the callee (for now, only .I FS_QSTAT_VERSION1 -is supported). Kernel will fill the structure in accordance with +is supported). +The kernel will fill the structure in accordance with version provided. The .I id @@ -614,13 +646,14 @@ value containing flags (the same as in .I d_flags field of .I fs_disk_quota -structure) which identify what types of quota should be removed (note that quota -type passed in +structure) which identify what types of quota should be removed +(note that the quota type passed in the .I cmd argument is ignored, but should remain valid in order to pass preliminary quotactl syscall handler checks). -Quotas must have already been turned off. The +Quotas must have already been turned off. +The .I id argument is ignored. .PP @@ -731,17 +764,17 @@ taking into account that there are several naming discrepancies: .IP \(bu 3 Quota enabling flags (of format .BR XFS_QUOTA_[UGP]DQ_{ACCT,ENFD} ) -are defined without leading "X", as +are defined without a leading "X", as .BR FS_QUOTA_[UGP]DQ_{ACCT,ENFD} . .IP \(bu -The same is applied to +The same is true for .B XFS_{USER,GROUP,PROJ}_QUOTA -quota type flags which are defined as +quota type flags, which are defined as .BR FS_{USER,GROUP,PROJ}_QUOTA . .IP \(bu The .I dqblk_xfs.h -defines its own +header file defines its own .BR XQM_USRQUOTA , .BR XQM_GRPQUOTA , and