quotactl(2)

ИМЯ
quotactl - управление дисковыми квотами

LIBRARY
Standard C library (libc, -lc)

СИНТАКСИС
#include <sys/quota.h>
#include <xfs/xqm.h> /* Definition of Q_X* and XFS_QUOTA_* constants
                        (or <linux/dqblk_xfs.h>; see NOTES) */

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

ОПИСАНИЕ
С помощью системы квот можно задать каждому пользователю, группе или проекту лимит использования дискового пространства. Для пользователя или группы в каждой файловой системе можно указать необязательный (soft) и обязательный (hard) лимиты. Обязательный лимит не может быть превышен. Необязательный лимит превышать можно, но будет выдано соответствующее предостережение. Более того, пользователь может превышать необязательный лимит только в течении льготного срока (по умолчанию,одна неделя); после этого необязательный лимит будет считаться обязательным.

Управление квотами выполняется с помощью вызова quotactl(). В аргументе cmd задаётся команда, которая должна быть применена для пользовательского или группового идентификатора, указанного в id. Для инициализации значения аргумента cmd используйте макрос QCMD(subcmd, type). Значение type может быть USRQUOTA (для пользовательских квот), GRPQUOTA (для групповых квот) или (начиная с Linux 4.1) PRJQUOTA (для проектных квот). Значение subcmd описано ниже.

Аргумент special представляет собой указатель на строку, завершающуюся null и содержащую путь к блочному устройству (смонтированному) с файловой системой, на которую накладывается квота.

The addr argument is the address of an optional, command-specific, data structure that is copied in or out of the system. The interpretation of addr is given with each operation below.

The subcmd value is one of the following operations:

Q_QUOTAON
    Включает учёт квот в файловой системе. В аргументе id задаётся используемый идентификационный номер формата квот. В настоящее время поддерживается три формата квот:

    QFMT_VFS_OLD
        Самая первая версия формата квот.

    QFMT_VFS_V0
        The standard VFS v0 quota format, which can handle 32-bit UIDs and GIDs and quota limits up to 2^42 bytes and 2^32 inodes.

    QFMT_VFS_V1
        A quota format that can handle 32-bit UIDs and GIDs and quota limits of 2^63 - 1 bytes and 2^63 - 1 inodes.

    The addr argument points to the pathname of a file containing the quotas for the filesystem. The quota file must exist; it is normally created with the quotacheck(8) program

    Quota information can be also stored in hidden system inodes for ext4, XFS, and other filesystems if the filesystem is configured so. In this case, there are no visible quota files and there is no need to use quotacheck(8). Quota information is always kept consistent by the filesystem and the Q_QUOTAON operation serves only to enable enforcement of quota limits. The presence of hidden system inodes with quota information is indicated by the DQF_SYS_FILE flag in the dqi_flags field returned by the Q_GETINFO operation.

    This operation requires privilege (CAP_SYS_ADMIN).

Q_QUOTAOFF
    Выключает учёт квот в файловой системе. Аргументы addr и id игнорируются. Данная операция требует дополнительных прав (CAP_SYS_ADMIN).

Q_GETQUOTA
    Возвращает данные по лимитам и текущее значение использованного пространства для пользователя или группы с заданным id. Аргумент addr является указателем на структуру dqblk, определённую в <sys/quota.h> следующим образом:

        /* uint64_t имеет тип unsigned 64-bit integer;
           uint32_t имеет тип unsigned 32-bit integer */

        struct dqblk {      /* определение, действующее с Linux 2.4.22 */
            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;       /* битовая маска констант
                                         QIF_* */
        };

        /* Флаги в dqb_valid указывают, какие поля в
           структуре dqblk являются рабочими. */

        #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 (начиная с 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
    Устанавливает квоты для пользователя или группы с указанным id, используя информацию из структуры dqblk, на которую указывает addr. Полем dqb_valid в структуре dqblk определяется какие элементы структуры установлены вызывающим. Эта операция заменяет предоставляемые прежде операции работы с квотами Q_SETQLIM и Q_SETUSE. Эта операция требует дополнительных прав (CAP_SYS_ADMIN).

Q_GETINFO (начиная с Linux 2.4.22)
    Возвращает информацию (например, льготное время (grace times)) о quotafile. Аргумент addr должен содержать указатель на структуру dqinfo. Эта структура определена в <sys/quota.h> следующим образом:

        /* uint64_t имеет тип unsigned 64-bit integer;
           uint32_t имеет тип unsigned 32-bit integer */

        struct dqinfo {         /* Defined since Linux 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;
        };

        /* биты из dqi_flags */

        /* формат квот QFMT_VFS_OLD */

        #define DQF_ROOT_SQUASH (1 << 0) /* включено ограничение для */
                      /* суперпользователя; до Linux v4.0 это было закрытым
                         определением с именем V1_DQF_RSQUASH */

        /* формат квот QFMT_VFS_V0 / QFMT_VFS_V1 */

        #define DQF_SYS_FILE    (1 << 16)   /* квота хранится в
                                               системном файле */

        /* флаги в dqi_valid, которые показывают какие поля в
           структуре dqinfo рабочие. */

        #define IIF_BGRACE  1
        #define IIF_IGRACE  2
        #define IIF_FLAGS   4
        #define IIF_ALL     (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)

    Значение поля dqi_valid в структуре dqinfo указывает на рабочие элементы. В настоящее время ядро заполняет все элементы структуры dqinfo и помечает их как рабочие в поле dqi_valid. Аргумент id игнорируется.

Q_SETINFO (начиная с Linux 2.4.22)
    Задаёт информацию о quotafile. Значение аргумента addr должно быть указателем на структуру dqinfo. Полем dqi_valid в структуре dqinfo определяется, какие элементы структуры установлены вызывающим. Эта операция заменяет операции Q_SETGRACE и Q_SETFLAGS из предоставляемых прежде операций работы с квотами. Аргумент id игнорируется. Эта операция требует дополнительных прав (CAP_SYS_ADMIN).

Q_GETFMT (начиная с Linux 2.4.22)
    Возвращает формат квоты, используемый в указанной файловой системе. В аргументе addr должен содержаться указатель на 4-байтовый буфер, в который будет записан номер формата.

Q_SYNC
    Обновляет дисковую копию используемых квот в файловой системе. Если значение special равно NULL, то действующие квоты будут синхронизированы на всех файловых системах. Аргументы addr и id игнорируются.

Q_GETSTATS (поддерживалась до Linux 2.4.21)
    Возвращает статистику и другую общую информацию о подсистеме квот. Аргумент addr должен содержать указатель на структуру dqstats, в которую нужно сохранить данные. Эта структура определена в <sys/quota.h>. Аргументы special и id игнорируются.

    Эта операция устарела и была удалена в Linux 2.4.22. Информацию можно получить из файлов в /proc/sys/fs/quota/.

For XFS filesystems making use of the XFS Quota Manager (XQM), the above operations are bypassed and the following operations are used:

Q_XQUOTAON
    Turn on quotas for an XFS filesystem. XFS provides the ability to turn on/off quota limit enforcement with quota accounting. Therefore, XFS expects addr to be a pointer to an unsigned int that contains a bitwise combination of the following flags (defined in <xfs/xqm.h>):

        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
    Turn off quotas for an XFS filesystem. As with Q_QUOTAON, XFS filesystems expect a pointer to an unsigned int that specifies whether quota accounting and/or limit enforcement need to be turned off (using the same flags as for Q_XQUOTAON operation). This operation requires privilege (CAP_SYS_ADMIN). The id argument is ignored.

Q_XGETQUOTA
    Возвращает данные по лимитам и текущее значение использованного пространства для пользователя id. Аргумент addr является указателем на структуру fs_disk_quota, определённую в <xfs/xqm.h> следующим образом:

        /* все части blk в BB (Basic Blocks)
           размером 512 байт */

        #define FS_DQUOT_VERSION  1  /* fs_disk_quota.d_version */

        #define XFS_USER_QUOTA    (1<<0)  /* тип пользовательской квоты */
        #define XFS_PROJ_QUOTA    (1<<1)  /* тип проектной квоты */
        #define XFS_GROUP_QUOTA   (1<<2)  /* тип групповой квоты */

        struct fs_disk_quota {
            int8_t   d_version;   /* версия данной структуры */
            int8_t   d_flags;     /* XFS_{USER,PROJ,GROUP}_QUOTA */
            uint16_t d_fieldmask; /* определитель поля */
            uint32_t d_id;        /* ID пользователя, группы или проекта */
            uint64_t d_blk_hardlimit; /* абсолютный лимит на
                                         дисковые блоки */
            uint64_t d_blk_softlimit; /* предпочтительный лимит на
                                         дисковые блоки */
            uint64_t d_ino_hardlimit; /* максимальное кол-во выделяемых
                                         инод */
            uint64_t d_ino_softlimit; /* предпочтительный лимит на иноды */
            uint64_t d_bcount;    /* # кол-во дисковых блоков,
                                     принадлежащих пользователю */
            uint64_t d_icount;    /* # кол-во инод, принадлежащих пользователю */
            int32_t  d_itimer;    /* ноль, если лимит на иноды не превышен */
                                  /* если нет, то нам отказывают */
            int32_t  d_btimer;    /* подобное предыдущему, но для
                                     дисковых блоков */
            uint16_t d_iwarns;    /* кол-во предупреждений в соответствии с
                                     кол-вом инод */
            uint16_t d_bwarns;    /* кол-во предупреждений в соответствии с
                                     кол-вом дисковых блоков */
            int32_t  d_padding2;  /* заполнитель, для использования в будущем */
            uint64_t d_rtb_hardlimit; /* абсолютный лимит на работу с дисковыми
                                         блоками в реальном времени (RT) */
            uint64_t d_rtb_softlimit; /* предпочтительный лимит на дисковые блоки
                                         в RT */
            uint64_t d_rtbcount;  /* кол-во дисковых блоков под реальное время */
            int32_t  d_rtbtimer;  /* подобное предыдущему, но
                                     для дисковых блоков RT */
            uint16_t d_rtbwarns;  /*  кол-во предупреждений в соответствии с
                                     дисковыми блоками RT */
            int16_t  d_padding3;  /* заполнитель, для использования в будущем */
            char     d_padding4[8];   /* ещё заполнитель */
        };

    Непривилегированные пользователи могут получить данные только по своим квотам; привилегированный пользователь (с CAP_SYS_ADMIN) может получить информацию о квотах любого пользователя.

Q_XGETNEXTQUOTA (начиная с Linux 4.6)
    This operation is the same as Q_XGETQUOTA, but it returns (in the fs_disk_quota structure pointed by addr) quota information for the next ID greater than or equal to id that has a quota set. Note that since fs_disk_quota already has q_id field, no separate structure type is needed (in contrast with Q_GETQUOTA and Q_GETNEXTQUOTA operations)

Q_XSETQLIM
    Устанавливает дисковую квоту для пользователя с указанным id. В аргументе addr задаётся указатель на структуру fs_disk_quota. Эта операция требует прав (CAP_SYS_ADMIN).

Q_XGETQSTAT
    Возвращает доступную только в XFS информацию о квоте в структуре fs_quota_stat, на которую указывает addr. Это полезно для определения количества пространства, использованного для хранения информации о квоте, а также для получения состояния включения/отключения квоты определённой локальной файловой системы XFS. Структура fs_quota_stat определена следующим образом:

        #define FS_QSTAT_VERSION 1  /* fs_quota_stat.qs_version */

        struct fs_qfilestat {
            uint64_t qfs_ino;       /* номер иноды */
            uint64_t qfs_nblks;     /* количество BB блоков
                                       размером 512 байт */
            uint32_t qfs_nextents;  /* количество экстентов */
        };

        struct fs_quota_stat {
            int8_t   qs_version; /* номер версии
                                    для изменений в будущем */
            uint16_t qs_flags; /* XFS_QUOTA_{U,P,G}DQ_{ACCT,ENFD} */
            int8_t   qs_pad;   /* не используется */
            struct fs_qfilestat qs_uquota;  /* информация о хранилище
                                               пользовательской квоты */
            struct fs_qfilestat qs_gquota;  /* информация о хранилище
                                               групповой квоты */
            uint32_t qs_incoredqs;   /* количество dquots в ядре */
            int32_t  qs_btimelimit;  /* лимит для таймера на блоки*/
            int32_t  qs_itimelimit;  /* лимит для таймера на иноды */
            int32_t  qs_rtbtimelimit;/* лимит для таймера на
                                        блоки RT */
            uint16_t qs_bwarnlimit;  /* лимит на количество предупреждений */
            uint16_t qs_iwarnlimit;  /* лимит на количество предупреждений */
        };

    Аргумент id игнорируется.

Q_XGETQSTATV
    Returns XFS filesystem-specific quota information in the fs_quota_statv pointed to by addr. This version of the operation 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 fs_quota_statv structure itself is defined as follows:

        #define FS_QSTATV_VERSION1 1 /* fs_quota_statv.qs_version */

        struct fs_qfilestatv {
            uint64_t qfs_ino;       /* номер иноды */
            uint64_t qfs_nblks;     /* количество BB блоков
                                       размером 512 байт */
            uint32_t qfs_nextents;  /* количество экстентов */
            uint32_t qfs_pad;       /* заполнитель для 8-байтового выравнивания */
        };

        struct fs_quota_statv {
            int8_t   qs_version;    /* версия для изменений
                                       в будущем */
            uint8_t  qs_pad1;       /* заполнитель для 16-битного выравнивания */
            uint16_t qs_flags;      /* флаги XFS_QUOTA_.* */
            uint32_t qs_incoredqs;  /* количество dquots incore */
            struct fs_qfilestatv qs_uquota;  /* информация
                                                о пользовательской квоте */
            struct fs_qfilestatv qs_gquota;  /* информация
                                                о групповой квоте */
            struct fs_qfilestatv qs_pquota;  /* информация
                                                о проектной квоте */
            int32_t  qs_btimelimit;   /* лимит по таймеру на блоки */
            int32_t  qs_itimelimit;   /* лимит по таймеру на иноды */
            int32_t  qs_rtbtimelimit; /* лимит по таймеру
                                         на блоки RT */
            uint16_t qs_bwarnlimit;   /* лимит на кол-во предупреждений */
            uint16_t qs_iwarnlimit;   /* лимит на кол-во предупреждений */
            uint64_t qs_pad2[8];      /* для использования в будущем */
        };

    Поле qs_version должно быть заполнено версией структуры, поддерживаемой вызываемым (пока поддерживается только FS_QSTAT_VERSION1). Ядро заполнит структуру согласно предоставленной версии. Аргумент id игнорируется.

Q_XQUOTARM (buggy until Linux 3.16)
    Free the disk space taken by disk quotas. The addr argument should be a pointer to an unsigned int value containing flags (the same as in d_flags field of fs_disk_quota structure) which identify what types of quota should be removed. (Note that the quota type passed in the cmd argument is ignored, but should remain valid in order to pass preliminary quotactl syscall handler checks.)

    Квоты должны быть предварительно выключены. Аргумент id игнорируется.

Q_XQUOTASYNC (начиная с Linux 2.6.15; ничего не делает начиная с Linux 3.4)
    This operation was an XFS quota equivalent to Q_SYNC, but it is no-op since Linux 3.4, as sync(1) writes quota information to disk now (in addition to the other filesystem metadata that it writes out). The special, id and addr arguments are ignored.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении quotactl() возвращается 0; при ошибке возвращается -1, а в errno содержится код ошибки.

ОШИБКИ

EACCES
    Значение cmd равно Q_QUOTAON и файл квот, указанный в addr, существует, но не является обычным файлом или находится не в файловой системе, указанной в special.

EBUSY
    Значение cmd равно Q_QUOTAON, но уже выполняется другой запуск Q_QUOTAON.

EFAULT
    Неверное значение addr или special.

EINVAL
    Неверное значение cmd или type.

EINVAL
    Значение cmd равно Q_QUOTAON, но указанный файл квот повреждён.

EINVAL (начиная с Linux 5.5)
    cmd is Q_XQUOTARM, but addr does not point to valid quota types.

ENOENT
    Файл, указанный в special или addr, не существует.

ENOSYS
    Ядро собрано с выключенным параметром CONFIG_QUOTA.

ENOTBLK
    Значение special не указывает на блочное устройство.

EPERM
    Вызывающий не имеет необходимых прав (CAP_SYS_ADMIN) для выполнения указанной операции.

ERANGE
    Значение cmd равно Q_SETQUOTA, но заданный лимит вне диапазона допустимого форматом квот.

ESRCH
    Не найдена дисковая квота для заданного пользователя. Квоты выключены в файловой системе.

ESRCH
    Значение cmd равно Q_QUOTAON, но заданный формат квот не найден.

ESRCH
    Значение cmd равно Q_GETNEXTQUOTA или Q_XGETNEXTQUOTA, но нет ID, который больше или равен id с активной квотой.

ЗАМЕЧАНИЯ
Вместо <xfs/xqm.h> может быть использован <linux/dqblk_xfs.h>, но следует учесть, что есть несколько несоответствий названий:

•   Флаги включения квот (формата 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)

ПЕРЕВОД
Русский перевод этой страницы руководства был сделан Artyom Kunyov <artkun@guitarplayer.ru>, Azamat Hackimov <azamat.hackimov@gmail.com>, Konstantin Shvaykovskiy <kot.shv@gmail.com> и Yuri Kozlov <yuray@komyakino.ru>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 (https://www.gnu.org/licenses/gpl-3.0.html) или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.