QUOTACTL - Linux手册页

时间:2019-08-20 17:59:11  来源:igfitidea点击:

Linux程序员手册 第2部分
更新日期: 2020-04-11

名称

quotactl-操作磁盘配额

语法

#include <sys/quota.h>
#include <xfs/xqm.h> /* for XFS quotas */

int quotactl(int cmd, const char *special, int id, caddr_t addr);

说明

配额系统可用于为文件系统上使用的磁盘空间量设置每个用户,每个组和每个项目的限制。对于每个用户和/或组,可以为每个文件系统设置软限制和硬限制。不能超过硬限制。可以超出软限制,但是会出现警告。此外,用户一次不能超过软限制超过宽限期的持续时间(默认为一周);此后,软限制将算作硬限制。

quotactl()调用可操纵磁盘配额。 cmd参数指示要应用于id中指定的用户或组ID的命令。若要初始化cmd参数,请使用QCMD(subcmd,type)宏。对于用户配额,类型值是USRQUOTA;对于组配额,类型值是GRPQUOTA;对于项目配额,类型值是(自Linux 4.1起)PRJQUOTA。 subcmd值如下所述。

special参数是一个指向以空字符结尾的字符串的指针,该字符串包含要处理的文件系统的(已安装)块特殊设备的路径名。

addr参数是一个可选的,特定于命令的数据结构的地址,该数据结构被复制到系统中或从系统中复制出来。下面的每个操作都对addr进行了解释。

subcmd值是以下操作之一:

Q_QUOTAON
Turn on quotas for a filesystem. The id

argument is the identification number of the quota format to be used.
Currently, there are three supported quota formats:

QFMT_VFS_OLD
原始配额格式。
QFMT_VFS_V0
标准VFS v0配额格式,可以处理32位UID和GID以及配额限制,最大限制为2 ^ 42字节和2 ^ 32 inode。
QFMT_VFS_V1
可以处理32位UID和GID的配额格式,以及2 ^ 64字节和2 ^ 64 inode的配额限制。
addr参数指向包含文件系统配额的文件的路径名。配额文件必须存在;通常是使用quotacheck(8)程序创建的
配额信息也可以存储在ext4,XFS和其他文件系统的隐藏系统inode中(如果已配置文件系统)。在这种情况下,没有可见的配额文件,也不需要使用quotacheck(8)。文件系统始终将配额信息保持一致,并且Q_QUOTAON操作仅用于实现配额限制。 Q_GETINFO操作返回的dqi_flags字段中的DQF_SYS_FILE标志指示带有配额信息的隐藏系统inode的存在。
此操作需要特权(CAP_SYS_ADMIN)。
Q_QUOTAOFF
关闭文件系统的配额。 addr和id参数将被忽略。此操作需要特权(CAP_SYS_ADMIN)。
Q_GETQUOTA
获取磁盘配额限制和用户或组ID的当前使用情况。 addr参数是指向dqblk结构的指针,其定义如下:
/* uint64_t is an unsigned 64-bit integer;
   uint32_t is an unsigned 32-bit integer */

struct dqblk {      /* Definition since Linux 2.4.22 */
    uint64_t dqb_bhardlimit;  /* Absolute limit on disk
                                 quota blocks alloc */
    uint64_t dqb_bsoftlimit;  /* Preferred limit on
                                 disk quota blocks */
    uint64_t dqb_curspace;    /* Current occupied space
                                 (in bytes) */
    uint64_t dqb_ihardlimit;  /* Maximum number of
                                 allocated inodes */
    uint64_t dqb_isoftlimit;  /* Preferred inode limit */
    uint64_t dqb_curinodes;   /* Current number of
                                 allocated inodes */
    uint64_t dqb_btime;       /* Time limit for excessive
                                 disk use */
    uint64_t dqb_itime;       /* Time limit for excessive
                                 files */
    uint32_t dqb_valid;       /* Bit mask of QIF_*
                                 constants */
};

/* Flags in dqb_valid that indicate which fields in
   dqblk structure are valid. */

#define QIF_BLIMITS   1
#define QIF_SPACE     2
#define QIF_ILIMITS   4
#define QIF_INODES    8
#define QIF_BTIME     16
#define QIF_ITIME     32
#define QIF_LIMITS    (QIF_BLIMITS | QIF_ILIMITS)
#define QIF_USAGE     (QIF_SPACE | QIF_INODES)
#define QIF_TIMES     (QIF_BTIME | QIF_ITIME)
#define QIF_ALL       (QIF_LIMITS | QIF_USAGE | QIF_TIMES)
dqb_valid字段是位掩码,设置为指示dqblk结构中有效的条目。当前,内核会填充dqblk结构的所有条目,并在dqb_valid字段中将其标记为有效。非特权用户只能检索自己的配额;特权用户(CAP_SYS_ADMIN)可以检索任何用户的配额。
Q_GETNEXTQUOTA(since Linux 4.6)
此操作与Q_GETQUOTA相同,但是它将返回大于或等于已设置配额的id的下一个ID的配额信息。
addr参数是一个指向nextdqblk结构的指针,该结构的字段与dqblk相同,只是增加了一个dqb_id字段,该字段用于返回要为其返回配额信息的ID:
struct nextdqblk {
    uint64_t dqb_bhardlimit;
    uint64_t dqb_bsoftlimit;
    uint64_t dqb_curspace;
    uint64_t dqb_ihardlimit;
    uint64_t dqb_isoftlimit;
    uint64_t dqb_curinodes;
    uint64_t dqb_btime;
    uint64_t dqb_itime;
    uint32_t dqb_valid;
    uint32_t dqb_id;
};
Q_SETQUOTA
使用addr指向的dqblk结构中提供的信息,为用户或组ID设置配额信息。 dqblk结构的dqb_valid字段指示调用者已在结构中设置了哪些条目。此操作将替代以前的配额接口中的Q_SETQLIM和Q_SETUSE操作。此操作需要特权(CAP_SYS_ADMIN)。
Q_GETINFO(since Linux 2.4.22)
获取有关配额文件的信息(例如宽限时间)。 addr参数应该是dqinfo结构的指针。此结构定义如下:
/* uint64_t is an unsigned 64-bit integer;
   uint32_t is an unsigned 32-bit integer */

struct dqinfo {         /* Defined since kernel 2.4.22 */
    uint64_t dqi_bgrace;  /* Time before block soft limit
                             becomes hard limit */
    uint64_t dqi_igrace;  /* Time before inode soft limit
                             becomes hard limit */
    uint32_t dqi_flags;   /* Flags for quotafile
                             (DQF_*) */
    uint32_t dqi_valid;
};

/* Bits for dqi_flags */

/* Quota format QFMT_VFS_OLD */

#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 */

/* 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_ALL     (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)
dqinfo结构中的dqi_valid字段指示结构中有效的条目。当前,内核会填充dqinfo结构的所有条目,并在dqi_valid字段中将其全部标记为有效。 id参数将被忽略。
Q_SETINFO(since Linux 2.4.22)
设置有关配额文件的信息。 addr参数应该是dqinfo结构的指针。 dqinfo结构的dqi_valid字段指示结构中已由调用方设置的条目。此操作将替代以前的配额接口中的Q_SETGRACE和Q_SETFLAGS操作。 id参数将被忽略。此操作需要特权(CAP_SYS_ADMIN)。
Q_GETFMT(since Linux 2.4.22)
获取在指定文件系统上使用的配额格式。 addr参数应该是一个指向将存储格式编号的4字节缓冲区的指针。
Q_SYNC
更新文件系统配额使用的磁盘上副本。如果special为NULL,则将同步所有具有活动配额的文件系统。 addr和id参数将被忽略。
Q_GETSTATS(supported up to Linux 2.4.21)
获取有关配额子系统的统计信息和其他常规信息。 addr参数应该是指向dqstats结构的指针,该结构中应存储数据。此结构在中定义。 special和id参数将被忽略。
该操作已过时,已在Linux 2.4.22中删除。 / proc / sys / fs / quota /中的文件将携带该信息。

对于使用XFS配额管理器(XQM)的XFS文件系统,将绕过上述操作,并使用以下操作:

Q_XQUOTAON
打开XFS文件系统的配额。 XFS提供了使用配额核算打开/关闭配额限制实施的功能。因此,XFS期望addr是指向无符号int的指针,该int包含以下标志(在中定义)的按位组合:
XFS_QUOTA_UDQ_ACCT  /* User quota accounting */
XFS_QUOTA_UDQ_ENFD  /* User quota limits enforcement */
XFS_QUOTA_GDQ_ACCT  /* Group quota accounting */
XFS_QUOTA_GDQ_ENFD  /* Group quota limits enforcement */
XFS_QUOTA_PDQ_ACCT  /* Project quota accounting */
XFS_QUOTA_PDQ_ENFD  /* Project quota limits enforcement */
此操作需要特权(CAP_SYS_ADMIN)。 id参数将被忽略。
Q_XQUOTAOFF
关闭XFS文件系统的配额。与Q_QUOTAON一样,XFS文件系统期望指向无符号int的指针,该指针指定是否需要关闭配额计费和/或限制实施(使用与Q_XQUOTAON操作相同的标志)。此操作需要特权(CAP_SYS_ADMIN)。 id参数将被忽略。
Q_XGETQUOTA
获取磁盘配额限制和用户ID的当前使用情况。 addr参数是fs_disk_quota结构的指针,该结构的定义如下:
/* All the blk units are in BBs (Basic Blocks) of
   512 bytes. */

#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 */

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 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 */
};
非特权用户只能检索自己的配额;特权用户(CAP_SYS_ADMIN)可以检索任何用户的配额。
Q_XGETNEXTQUOTA(since Linux 4.6)
此操作与Q_XGETQUOTA相同,但是它返回(在addr指向的fs_disk_quota结构中)下一个大于或等于已设置配额的ID的配额信息。请注意,由于fs_disk_quota已经具有q_id字段,因此不需要单独的结构类型(与Q_GETQUOTA和Q_GETNEXTQUOTA操作相反)
Q_XSETQLIM
设置用户ID的磁盘配额限制。 addr参数是指向fs_disk_quota结构的指针。此操作需要特权(CAP_SYS_ADMIN)。
Q_XGETQSTAT
在addr指向的fs_quota_stat结构中返回特定于XFS文件系统的配额信息。这对于找出多少空间用于存储配额信息,以及获取给定本地XFS文件系统的配额开/关状态很有用。 fs_quota_stat结构本身定义如下:
#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-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 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 */
};
id参数将被忽略。
Q_XGETQSTATV
在addr指向的fs_quota_statv中返回特定于XFS文件系统的配额信息。此版本的操作使用具有适当版本控制支持的结构,以及适当的布局(所有字段都自然对齐)和填充,以避免特殊的兼容性处理。它还提供了获取有关项目配额文件的统计信息的功能。 fs_quota_statv结构本身定义如下:
#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-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 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 */
};
结构的qs_version字段应使用被调用方支持的结构的版本填充(目前仅支持FS_QSTAT_VERSION1)。内核将按照提供的版本填充结构。 id参数将被忽略。
Q_XQUOTARM (since Linux 3.16)
释放磁盘配额占用的磁盘空间。 addr参数应该是指向包含标志(与fs_disk_quota结构的d_flags字段中的标志相同)的无符号int值的指针,这些标志标识应删除哪些类型的配额。 (请注意,在cmd参数中传递的配额类型将被忽略,但应保持有效,以便通过初步quotactl syscall处理程序检查。)
配额必须已经关闭。 id参数将被忽略。
Q_XQUOTASYNC(since Linux 2.6.15; no-op since Linux 3.4)
此操作是等效于Q_SYNC的XFS配额,但是从Linux 3.4开始它是空运的,因为sync(1)现在将配额信息写入磁盘(除了它写入的其他文件系统元数据之外)。特殊的id和addr参数将被忽略。

返回值

成功时,quotactl()返回0;否则,返回0。如果返回错误-1,则返回错误,并且设置errno以指示错误。

错误说明

EACCES
cmd是Q_QUOTAON,并且addr指向的配额文件存在,但不是常规文件,或者不在special指向的文件系统上。
EBUSY
cmd是Q_QUOTAON,但是已经执行了另一个Q_QUOTAON。
EFAULT
addr或special无效。
EINVAL
cmd或类型无效。
EINVAL
cmd是Q_QUOTAON,但是指定的配额文件已损坏。
EINVAL(since Linux 5.5)
cmd是Q_XQUOTARM,但是addr不会指向有效的配额类型。
ENOENT
由special或addr指定的文件不存在。
ENOSYS
尚未使用CONFIG_QUOTA选项编译内核。
ENOTBLK
特殊不是块设备。
EPERM
调用者缺少指定操作的必需特权(CAP_SYS_ADMIN)。
ERANGE
cmd是Q_SETQUOTA,但是指定的限制超出了配额格式允许的范围。
ESRCH
找不到指定用户的磁盘配额。此文件系统的配额尚未打开。
ESRCH
cmd是Q_QUOTAON,但是找不到指定的配额格式。
ESRCH
cmd是Q_GETNEXTQUOTA或Q_XGETNEXTQUOTA,但是没有ID大于或等于具有有效配额的ID。

备注

考虑到一些命名差异,而不是可以使用,

*
配额启用标志(格式为XFS_QUOTA_ [UGP] DQ_ {ACCT,ENFD})定义为不带前导" X"的FS_QUOTA_ [UGP] DQ_ {ACCT,ENFD}。
*
XFS_ {USER,GROUP,PROJ} _QUOTA配额类型标志也是如此,它们被定义为FS_ {USER,GROUP,PROJ} _QUOTA。
*
dqblk_xfs.h头文件为可用配额类型定义了自己的XQM_USRQUOTA,XQM_GRPQUOTA和XQM_PRJQUOTA常量,但是它们的值与没有XQM_前缀的常量相同。

另外参见

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

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本,请访问https://www.kernel.org/doc/man-pages/