quotactl(2) управление дисковыми квотами

ОБЗОР

#include <sys/quota.h>
#include <xfs/xqm.h>
int quotactl(int cmd, const char *special, int id, caddr_t addr);

ОПИСАНИЕ

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

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

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

Аргумент addr представляет собой адрес необязательной, зависящей от команды, структуры данных, которые копируются в или из системы. Интерпретация addr указана ниже (для каждой команды).

Значением subcmd может быть одно из:

Q_QUOTAON
Включает учёт квот в файловой системе. В аргументе id задаётся используемый идентификационный номер формата квот. В настоящее время поддерживается три формата квот:
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). Данная операция требует дополнительных прав (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;   /* максимальное количество
                                  выделенных inode */
    uint64_t dqb_isoftlimit;   /* предпочтительных лимит по inode */
    uint64_t dqb_curinodes;    /* текущее количество
                                  выделенных inode */
    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_SETQUOTA
Устанавливает квоты для пользователя или группы с указанным id, используя информацию из структуры dqblk, на которую указывает addr. Полем dqb_valid в структуре dqblk определяется какие элементы структуры установлены вызывающим. Эта операция заменяет предоставляемые прежде операции работы с квотами Q_SETQLIM и Q_SETUSE. Эта операция требует дополнительных прав (CAP_SYS_ADMIN).
Q_GETINFO
Возвращает информацию (например, льготное время (grace times)) о quotafile. Аргумент addr должен содержать указатель на структуру dqinfo. Эта структура определена в <sys/quota.h> следующим образом:
/* uint64_t имеет тип unsigned 64-bit integer;
   uint32_t имеет тип unsigned 32-bit integer */
struct dqinfo {         /* начиная с ядра 2.4.22 */
    uint64_t dqi_bgrace;    /* время, перед тем как необязательный предел
                               для блока станет обязательным */
    uint64_t dqi_igrace;    /* время, перед тем как необязательный предел
                               для inode станет обязательным */
    uint32_t dqi_flags;     /* флаги quotafile
                               (DQF_*) */
    uint32_t dqi_valid;
};
/* биты из dqi_flags */
/* формат квот QFMT_VFS_OLD */
#define V1_DQF_RSQUASH  1   /* включён режим сброса прав root (root squash) */
/* в других форматах квот биты dqi_flags не определены */
/* флаги в 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
Задаёт информацию о quotafile. Значение аргумента addr должно быть указателем на структуру dqinfo. Полем dqi_valid в структуре dqinfo определяется, какие элементы структуры установлены вызывающим. Эта операция заменяет операции Q_SETGRACE и Q_SETFLAGS из предоставляемых прежде операций работы с квотами. Аргумент id игнорируется. Эта операция требует дополнительных прав (CAP_SYS_ADMIN).
Q_GETFMT
Возвращает формат квоты, используемый в указанной файловой системе. В аргументе addr должен содержаться указатель на 4-байтовый буфер, в который будет записан номер формата.
Q_SYNC
Обновляет дисковую копию используемых квот в файловой системе. Если значение special равно NULL, то действующие квоты будут синхронизированы на всех файловых системах. Аргументы addr и id игнорируются.
Q_GETSTATS
Возвращает статистику и другую общую информацию о подсистеме квот. Аргумент addr должен содержать указатель на структуру dqstats, в которую нужно сохранить данные. Эта структура определена в <sys/quota.h>. Аргументы special и id игнорируются. Эта операция устарела и не поддерживается новыми ядрами. Информацию можно получить из файлов в /proc/sys/fs/quota/.

Для файловых систем XFS, использующих XFS Quota Manager (XQM), приведённые выше команды не выполняются, а используются следующие команды:

Q_XQUOTAON
Включает квоты для файловой системы XFS. XFS позволяет включать/выключать применение квот с ведением учёта. Поэтому для XFS в addr ожидается указатель на unsigned int, который представляет собой или флаги XFS_QUOTA_UDQ_ACCT и/или XFS_QUOTA_UDQ_ENFD (для пользовательской квоты), или XFS_QUOTA_GDQ_ACCT и/или XFS_QUOTA_GDQ_ENFD (для квот на группу), определённые в <xfs/xqm.h>. Эта операция требует дополнительных прав (CAP_SYS_ADMIN).
Q_XQUOTAOFF
Выключает квоты для файловой системы XFS. Как в Q_QUOTAON, для файловых систем XFS ожидается указатель на unsigned int, в котором задаётся что нужно отключить: учёт или применение квот. Эта операция требует дополнительных прав (CAP_SYS_ADMIN).
Q_XGETQUOTA
Возвращает дисковые квоты и текущее использование для пользователя с указанным id. В addr содержится указатель на структуру fs_disk_quota (определена в <xfs/xqm.h>). Непривилегированные пользователи могут получить данные только по своим квотам; привилегированный пользователь (с CAP_SYS_ADMIN) может получить информацию о квотах любого пользователя.
Q_XSETQLIM
Устанавливает дисковую квоту для пользователя с указанным id. В аргументе addr задаётся указатель на структуру fs_disk_quota (определена в <xfs/xqm.h>). Эта операция требует дополнительных прав (CAP_SYS_ADMIN).
Q_XGETQSTAT
Возвращает структуру fs_quota_stat, в которой содержится информация о квотах, которая доступна только для файловой системы XFS. Она полезна для определения пространства, использованного для хранения информации о квотах, а также для получения состояния включённых/отключённых квот в заданной локальной файловой системе XFS.
Q_XQUOTARM
Освобождает дисковое пространство, занятое под квоты. Квоты должны быть выключены.

Для XFS нет эквивалента команде Q_SYNC, так как sync(1) записывает информацию о квотах на диск (вместе с другими метаданными файловой системы).

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

При успешном выполнении quotactl() возвращается 0; при ошибке возвращается -1, а в errno содержится код ошибки.

ОШИБКИ

EFAULT
Неверное значение addr или special.
EINVAL
Неверное значение cmd или type.
ENOENT
Файл, указанный в special или addr, не существует.
ENOSYS
Ядро собрано с выключенным параметром CONFIG_QUOTA.
ENOTBLK
Значение special не указывает на блочное устройство.
EPERM
Вызывающий не имеет необходимых прав (CAP_SYS_ADMIN) для выполнения указанной операции.
ESRCH
Не найдена дисковая квота для заданного пользователя. Квоты выключены в файловой системе.

Если значение cmd равно Q_SETQUOTA, то quotactl() также может присвоить errno следующее:

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

Если значение cmd равно Q_QUOTAON, то quotactl() также может присвоить errno следующее:

EACCES
Файл квот, указанный в addr, существует, но не является обычным файлом; или файл квот, указанный в addr, существует, но находится не на файловой системе, указанной в special.
EBUSY
Попытка выполнить Q_QUOTAON, но уже выполняется другой запуск Q_QUOTAON.
EINVAL
Файл квот повреждён.
ESRCH
Заданный формат квот не найден.