signalfd

title: signalfd(2)

text:
# signalfd(2)

## ИМЯ
signalfd - создаёт файловый дескриптор для приёма сигналов

## ОБЗОР
\#include <sys/signalfd.h>

int signalfd(int fd, const sigset_t *mask, int flags);

## ОПИСАНИЕ
Вызов signalfd() создаёт файловый дескриптор, который можно использовать для приёма сигналов, предназначенных вызывающему. Его можно использовать как замену обработчику сигналов или sigwaitinfo(2); преимущество в том, что за файловым дескриптором можно следить с помощью select(2), poll(2) и epoll(7).

В аргументе mask указывается набор сигналов, который вызывающий хочет принимать через файловый дескриптор. Этот аргумент, содержащий набор сигналов, можно инициализировать с помощью макросов, описанных в sigsetops(3). Обычно, набор сигналов, принимаемых через файловый дескриптор, должен блокироваться с помощью sigprocmask(2), чтобы предотвратить обработку сигналов назначенными им обработчиками по умолчанию. Через файловый дескриптор signalfd нельзя получить сигнал SIGKILL или SIGSTOP; при указании их в mask они просто игнорируются.

Если значение аргумента fd равно -1, то вызов создаёт новый файловый дескриптор и связывает с ним набор сигналов, указанный в mask. Если fd не равно -1, то в нём должен быть указан допустимый существующий файловый дескриптор signalfd, а значение mask используется для замены набора сигналов, связанного с этим файловым дескриптором.

Начиная с Linux 2.6.27, для изменения поведения signalfd() можно использовать следующие значения flags (через OR):

SFD_NONBLOCK

Устанавливает флаг состояния файла O_NONBLOCK для нового открытого файлового описания (смотрите open(2)), на которое ссылается новый файловый дескриптор. Использование данного флага делает ненужными дополнительные вызовы fcntl(2) для достижения того же результата.

SFD_CLOEXEC

Устанавливает флаг close-on-exec (FD_CLOEXEC) для нового открытого файлового дескриптора. Смотрите описание флага O_CLOEXEC в open(2) для того, чтобы узнать как это может пригодиться.

До версии Linux 2.6.26 аргумент flags не использовался, и должен быть равен нулю.

Вызов signalfd() возвращает файловый дескриптор, который поддерживает следующие операции:

read(2)

Если один или несколько сигналов, указанных в mask, ожидают обработки, то буфер, указанный в read(2), используется для возврата одной или нескольких структур signalfd_siginfo (см. ниже), описывающих сигналы. Вызов read(2) возвращает информацию о всех ожидающих сигналах, которые поместились в предоставленный буфер. Размер буфера должен быть не менее sizeof(struct signalfd_siginfo) байт. Возвращаемое read(2) значение представляет собой общее количество прочитанных байт.

После выполнения read(2) сигналы считаются учтёнными, они больше не считаются ожидающими обработки (т.е., они не будут переданы обработчикам сигналов и не могут быть приняты с помощью sigwaitinfo(2)).

Если ни один из сигналов из mask не ожидает обработки, то вызов read(2) или блокируется до поступления сигналов согласно mask, или завершается с ошибкой EAGAIN, если файловый дескриптор помечен как неблокируемый.

poll(2), select(2) (и подобные)

Файловый дескриптор доступен для чтения (в select(2) аргумент readfds; в poll(2) флаг POLLIN), если один или более сигналов из mask ожидают обработки.

Файловый дескриптор signalfd также поддерживает другие мультиплексные вызовы: pselect(2), ppoll(2) и epoll(7).

close(2)

Если файловый дескриптор больше не требуется, его нужно закрыть. Когда все файловые дескрипторы, связанные с одним объектом signalfd, будут закрыты, ядро освобождает ресурсы объекта.

### Структура signalfd_siginfo
Формат структур(ы) signalfd_siginfo, возвращаемых read(2) из файлового дескриптора signalfd, имеет следующий вид:

```
struct signalfd_siginfo {

    uint32_t ssi_signo;    /* номер сигнала */

    int32_t  ssi_errno;    /* номер ошибки (не используется) */

    int32_t  ssi_code;     /* код сигнала */

    uint32_t ssi_pid;      /* PID отправителя */

    uint32_t ssi_uid;      /* реальный UID отправителя */

    int32_t  ssi_fd;       /* файловый дескриптор (SIGIO) */

    uint32_t ssi_tid;      /* ID таймера ядра (таймеры POSIX)

    uint32_t ssi_band;     /* внутреннее событие (SIGIO) */

    uint32_t ssi_overrun;  /* счётчик переполнений таймера POSIX */

    uint32_t ssi_trapno;   /* номер ловушки, поймавшей сигнал */

    int32_t  ssi_status;   /* код выхода или сигнала (SIGCHLD) */

    int32_t  ssi_int;      /* целое, посланное sigqueue(3) */

    uint64_t ssi_ptr;      /* указатель, посланный sigqueue(3) */

    uint64_t ssi_utime;    /* пользовательское потреблённое

                              время ЦП (SIGCHLD) */

    uint64_t ssi_stime;    /* системное потреблённое

                              время ЦП (SIGCHLD) */

    uint64_t ssi_addr;     /* сгенерированный сигналом адрес

                              (для сигналов от аппаратуры) */

    uint16_t ssi_addr_lsb; /* наименее значимый бит адреса

                              (SIGBUS; начиная с Linux 2.6.37)

    uint8_t  pad[X];       /* заполнитель до 128 байт (для

                              будущих дополнительных полей) */
};
```

Каждое из полей в этой структуре аналогично полям с тем же именем в структуре siginfo_t. Структура siginfo_t описана в sigaction(2). Не все поля в возвращаемой структуре signalfd_siginfo будут заполнены правильно для каждого сигнала; набор допустимых полей можно определить по значению, возвращённому в поле ssi_code. Это поле является аналогом поля si_code в siginfo_t; подробней смотрите в sigaction(2).

### Поведение при fork(2)
После вызова fork(2) потомок наследует копию файлового дескриптора signalfd. Вызов read(2) для файлового дескриптора в потомке вернёт информацию о сигналах для потомка.

### Семантика передачи файлового дескриптора
Как и другие файловые дескрипторы, файловые дескрипторы signalfd можно передавать в другой процесс через доменный сокет UNIX (смотрите unix(7)). В принимающем процессе вызов read(2) из принятого файлового дескриптора возвратит информацию о сигналах в очереди этого процесса.

### Поведение при execve(2)
Как и любой файловый дескриптор, файловый дескриптор signalfd остаётся открытым после execve(2), если он не помечен как close-on-exec (см. fcntl(2)). Все сигналы, которые были доступны для чтения перед execve(2), остаются доступными и для новой загруженной программы (аналогично обычному поведению сигналов, когда блокированный сигнал, ожидающий обработки, остаётся в очереди ожидания после execve(2)).

### Поведение в нитях
Поведение файловых дескрипторов signalfd в многонитевых программах отражает стандартное поведение сигналов. Иначе говоря, когда нить выполняет чтение из файлового дескриптора signalfd, она прочтёт сигналы, которые предназначены самой нити и сигналы, предназначенные процессу (т.е., всей группе нитей). Нить не может прочитать сигналы, которые предназначены другим нитям процесса.

### Поведение epoll(7)
Если процесс добавляет (через epoll_ctl(2)) файловый дескриптор signalfd в экземпляр epoll(7), то epoll_wait(2) возвращает события только о сигналах, посланных этому процессу. В частности, если процесс после добавления использует fork() для создания дочернего процесса, то потомок получит возможность читать (read(2)) сигналы, которые ему посланы с помощью файлового дескриптора signalfd, но epoll_wait(2) не будет отражать готовность файлового дескриптора signalfd. Обойти эту проблему можно так: после fork(2) дочерний процесс закрывает файловый дескриптор signalfd, унаследованный от родительского процесса, создаёт другой файловый дескриптор signalfd и затем добавляет его в экземпляр epoll. Или же родитель и потомок могут отложить создание своих (отдельных) файловых дескрипторов signalfd и добавить их в экземпляр epoll после вызова fork(2).

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

## ОШИБКИ
EBADF

Неправильный файловый дескриптор в fd.

EINVAL

Значение fd не является правильным файловым дескриптором signalfd.

EINVAL

Неправильное значение flags или, для Linux 2.6.26 и старее, flags не равно 0.

EMFILE

Было достигнуто ограничение по количеству открытых файловых дескрипторов на процесс.

ENFILE

Достигнуто максимальное количество открытых файлов в системе.

ENODEV

Не удалось смонтировать (внутреннее) безымянное устройство inode.

ENOMEM

Недостаточно памяти для создания нового файлового дескриптора signalfd.

## ВЕРСИИ
Вызов signalfd() доступен в Linux, начиная с ядра 2.6.22. Поддержка в glibc появилась в версии 2.8. Системный вызов signalfd4() (см. ЗАМЕЧАНИЯ) доступен в Linux, начиная с ядра 2.6.27.

## СООТВЕТСТВИЕ СТАНДАРТАМ
Вызовы signalfd() и signalfd4() есть только в Linux.

## ЗАМЕЧАНИЯ
Процесс может создать несколько файловых дескрипторов signalfd. Это позволяет принимать различные сигналы через различные файловые дескрипторы (может быть полезно при слежении за файловым дескриптором с помощью select(2), poll(2) или epoll(7): прибытие различных сигналов делает готовым различные файловые дескрипторы). Если сигнал указан в mask для нескольких файловых дескрипторов, то появление этого сигнала можно прочесть (однократно) из любого файлового дескриптора.

Попытки включить SIGKILL и SIGSTOP в маску mask просто игнорируются.

Маску сигналов, используемую файловым дескриптором signalfd, можно посмотреть в записи соответствующего файлового дескриптора в каталоге процесса /proc/[pid]/fdinfo. Подробности смотрите в proc(5).

### Ограничения
Механизм signalfd нельзя использовать для приёма сигналов, генерируемых синхронно, например сигнала SIGSEGV при доступе по неправильному адресу памяти, или сигнала SIGFPE при математических ошибках. Такие сигналы можно поймать только через обработчик сигнала.

Как сказано выше, обычно все сигналы, принимаемые через signalfd(), блокируются. Если порождается дочерний процесс для выполнения вспомогательной программы (которой не нужен файловый дескриптор signalfd), то после вызова fork(2), обычно, нужно разблокировать эти сигналы перед вызовом execve(2) для того, чтобы вспомогательная программа видела все сигналы, которые она ожидает увидеть. Однако имейте в виду, что это может быть невозможно, если вспомогательная программа порождается не вами, а где-то в библиотечной функции, которую может вызывать программа. В таких случаях нужно использовать обычный обработчик сигналов, который пишет в файловый дескриптор, отслеживаемый select(2), poll(2) или epoll(7).

### Отличия между библиотекой C и ядром
Лежащий в основе системный вызов Linux требует дополнительного аргумента, size_t sizemask, в котором указывается размер аргумента mask. В обёрточной функции glibc signalfd() нет этого аргумента — требуемое для системного вызова значение добавляется библиотекой.

Существуют два системных вызова Linux: signalfd() и более новый signalfd4(). В первом системном вызове не реализован аргумент flags. Во втором системном вызове реализованы значения flags, описанные ранее. Начиная с glibc 2.9, обёрточная функция signalfd() использует signalfd4(), если он доступен.

## ДЕФЕКТЫ
В ядрах до версии 3.6.25, поля ssi_ptr и ssi_int не заполнялись данными, поступающими при посылке сигнала с помощью sigqueue(3).

## ПРИМЕР
Программа, представленная далее, принимает сигналы SIGINT и SIGQUIT через файловый дескриптор signalfd. Она завершает работу при приёме сигнала SIGQUIT. Вот сеанс работы в оболочке, демонстрирующий использование программы:

```
$ ./signalfd_demo
^C                   # Control-C генерирует SIGINT
Получен SIGINT
^C
Получен SIGINT
^\                    # Control-\ генерирует SIGQUIT
Получен SIGQUIT
$
```

### Исходный код программы

```
#include <sys/signalfd.h>
#include <signal.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
#define handle_error(msg) \

    do { perror(msg); exit(EXIT_FAILURE); } while (0)
int
main(int argc, char *argv[])
{

    sigset_t mask;

    int sfd;

    struct signalfd_siginfo fdsi;

    ssize_t s;

    sigemptyset(&mask);

    sigaddset(&mask, SIGINT);

    sigaddset(&mask, SIGQUIT);

    /* Заблокировать сигналы для того, чтобы они не обрабатывались

       их обработчиками по умолчанию */

    if (sigprocmask(SIG_BLOCK, &mask, NULL) == -1)

        handle_error("sigprocmask");

    sfd = signalfd(-1, &mask, 0);

    if (sfd == -1)

        handle_error("signalfd");

    for (;;) {

        s = read(sfd, &fdsi, sizeof(struct signalfd_siginfo));

        if (s != sizeof(struct signalfd_siginfo))

            handle_error("read");

        if (fdsi.ssi_signo == SIGINT) {

            printf("Получен SIGINT\n");

        } else if (fdsi.ssi_signo == SIGQUIT) {

            printf("Получен SIGQUIT\n");

            exit(EXIT_SUCCESS);

        } else {

            printf("Прочитан неожидаемый сигнал\n");

        }

    }
}
```

## СМОТРИТЕ ТАКЖЕ
eventfd(2), poll(2), read(2), select(2), sigaction(2), sigprocmask(2), sigwaitinfo(2), timerfd_create(2), sigsetops(3), sigwait(3), epoll(7), signal(7)


sigpending

package: man-pages-ru

title: sigpending(2)

summary: проверка ожидающих сигналов

text:
# sigpending(2)

## ИМЯ
sigpending, rt_sigpending - проверка ожидающих сигналов

## ОБЗОР
\#include <signal.h>

int sigpending(sigset_t *set);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

sigpending(): _POSIX_C_SOURCE

## ОПИСАНИЕ
Вызов sigpending() возвращает набор сигналов, которые ожидают доставки в вызвавшую нить (т.е., сигналы, возникшие пока были заблокированы). Маска ожидающих сигналов возвращается в set.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении функция sigpending() возвращает 0 и -1 при ошибке. В случае ошибки в errno указывается номер ошибки.

## ОШИБКИ
EFAULT

Аргумент set указывает на память в недопустимой части адресуемого пространства.

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Подробная информация о работе с наборами сигналов есть на странице sigsetops(3).

Если сигнал заблокирован и имеет обработчик «игнорировать», то он не добавляется в маску ожидающих сигналов при генерации.

Набор сигналов, ожидающих обработки в нити, представляет собой объединение набора сигналов, ожидающих обработки в этой нити и набора сигналов, ожидающих обработки всем процессом (см. signal(7)).

Потомок, созданный с помощью fork(2), первоначально имеет пустой набор ожидающих сигналов; набор ожидающих сигналов сохраняется при вызове execve(2).

### Отличия между библиотекой C и ядром
Первоначально, системный вызов Linux назывался sigpending(). Однако, с добавлением сигналов реального времени в Linux 2.2, 32-битный аргумент sigset_t неизменяемого размера, поддерживаемый этим системным вызовом, не мог больше использоваться. В результате был добавлен новый системный вызов rt_sigpending() с увеличенным типом sigset_t. У нового системного вызова появился второй аргумент, size_t sigsetsize, в котором указывается размер (в байтах) набора сигналов set. Обёрточная функция glibc sigpending() скрывает это и вызывает rt_sigpending(), если он есть в ядре.

## ДЕФЕКТЫ
В версиях glibc до 2.2.1 включительно, был дефект в обёрточной функции к sigpending(), из-за которого возвращалась некорректная информация об ожидающих сигналах реального времени.

## СМОТРИТЕ ТАКЖЕ
kill(2), sigaction(2), signal(2), sigprocmask(2), sigsuspend(2), sigsetops(3), signal(7)


sigprocmask

title: sigprocmask(2)

text:
# sigprocmask(2)

## ИМЯ
sigprocmask, rt_sigprocmask - проверка и изменение блокировки сигналов

## ОБЗОР
\#include <signal.h>

```
/* Прототип обёрточной функции glibc */
int sigprocmask(int how, const sigset_t *set, sigset_t *oldset);
```

```
/* Прототип используемого системного вызова */
int rt_sigprocmask(int how, const kernel_sigset_t *set,
                   kernel_sigset_t *oldset, size_t sigsetsize);
```

```
/* Прототип устаревшего системного вызова */
int sigprocmask(int how, const old_kernel_sigset_t *set,
                old_kernel_sigset_t *oldset);
```

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

sigprocmask(): _POSIX_C_SOURCE

## ОПИСАНИЕ
Вызов sigprocmask() используется для выборки и/или изменения маски сигналов вызывающей нити. Маска сигналов представляет собой набор сигналов, чья доставка в настоящее время заблокирована вызывающим (подробнее об этом смотрите также в signal(7)).

Работа вызова зависит от значения how:

SIG_BLOCK

Набор блокируемых сигналов — объединение текущего набора и аргумента set.

SIG_UNBLOCK

Сигналы в set удаляются из списка блокируемых сигналов. Допускается разблокировать незаблокированные сигналы.

SIG_SETMASK

Набор блокируемых сигналов приравнивается к аргументу set.

Если значение oldset не равно NULL, то предыдущее значение маски сигналов записывается в oldset.

Если значение set равно NULL, то маска сигналов не изменяется (т.е., значение how игнорируется), но текущее значение маски сигналов всё же возвращается в oldset (если его значение не равно NULL).

Функции для изменения и получения переменных с типом sigset_t («наборы сигналов») описаны в sigsetops(3).

Использование sigprocmask() в многонитевых процессах не определено; смотрите pthread_sigmask(3).

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении функция sigprocmask() возвращает 0 и -1 при ошибке. В случае ошибки в errno указывается номер ошибки.

## ОШИБКИ
EFAULT

Аргумент set или oldset указывает за пределы выделенного адресного пространства процесса.

EINVAL

Значение how некорректно или ядро не поддерживает размер, переданный в sigsetsize.

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Невозможно заблокировать SIGKILL или SIGSTOP. Попытка выполнить это просто игнорируется.

Каждая нить процесса имеют свою маску сигналов.

Потомок, создаваемый с помощью fork(2), наследует копию родительской маски сигналов; маска сигналов сохраняется при вызове execve(2).

Если генерируется сигнал SIGBUS, SIGFPE, SIGILL или SIGSEGV, а он заблокирован, то результат не определён, если сигнал был сгенерирован не из kill(3), sigqueue(3) или raise(3).

Подробная информация о работе с наборами сигналов есть на странице sigsetops(3).

Заметим, что разрешается (хотя не очень полезно) передавать в set и oldset значение NULL.

### Отличия между библиотекой C и ядром
Определение ядра sigset_t отличается по размеру от используемого в библиотеке C. В данной справочной странице оно упоминается как kernel_sigset_t (хотя в исходном коде ядра оно называется sigset_t).

Обёрточная функция glibc для sigprocmask() просто игнорирует попытки блокирования двух сигналов реального времени, которые используются внутри реализации NPTL. Подробности смотрите в nptl(7).

Изначально, системный вызов Linux назывался sigprocmask(). Однако из-за добавления сигналов реального времени в Linux 2.2, 32-битный тип sigset_t (который называется old_kernel_sigset_t в этой справочной странице) постоянного размера, поддерживаемый этим системным вызовом, перестал подходить для этой цели. В связи с этим был добавлен новый системный вызов rt_sigprocmask(), поддерживающий увеличенный тип sigset_t (который называется kernel_sigset_t в этой справочной странице). У нового системного вызова есть четвёртый аргумент, size_t sigsetsize, которым задаётся размер набора сигналов (в байтах) в set и oldset. В настоящее время этот аргумент должен задаваться постоянным определяемым архитектурой значением (равен sizeof(kernel_sigset_t)).

Обёрточная функция glibc sigprocmask() скрывает эти детали от нас, вызывая rt_sigprocmask(), если это необходимо ядру.

## СМОТРИТЕ ТАКЖЕ
kill(2), pause(2), sigaction(2), signal(2), sigpending(2), sigsuspend(2), pthread_sigmask(3), sigqueue(3), sigsetops(3), signal(7)


sigreturn

title: sigreturn(2)

text:
# sigreturn(2)

## ИМЯ
sigreturn, rt_sigreturn - выполняет возврат из обработчика сигнала и очищает кадр стека

## ОБЗОР
int sigreturn(...);

## ОПИСАНИЕ
Если ядро Linux обнаруживает, что неблокированный сигнал ожидает обработки процессом, то при следующем переключении в пользовательский режим в этом процессе (например, при возврате из системного вызова или когда процесс перепланируется на ЦП), оно создаёт новый кадр в стеке пользовательского пространства, где сохраняет различные части контекста процесса (состояние слова процессора, регистры, маску сигналов и настройки стека сигналов).

Также ядро делает так, что при переходе в пользовательский режим вызывается обработчик сигналов и при возврате из обработчика управление передаётся части кода пользовательского пространства, называемого «сигнальным батутом»(signal trampoline). Код сигнального батута, в свою очередь, вызывает sigreturn().

Вызов sigreturn() очищает всё что накопилось — изменяет маску сигнала процесса, переключает стеки сигналов (см. sigaltstack(2)) — чтобы вызвать обработчик сигнала. Используя информацию, которая была ранее сохранена в стеке пользовательского пространства, sigreturn() восстанавливает маску сигналов процесса, переключает стеки и восстанавливает контекст процесса (регистры и флаги процессора, включая указатель стека и инструкций), так что процесс непосредственно возобновляет исполнение с точки где был прерван сигналом.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Вызов sigreturn() не возвращает значений.

## СООТВЕТСТВИЕ СТАНДАРТАМ
Во многих системах UNIX есть системный вызов sigreturn() или его эквивалент. Однако этот вызов отсутствует в POSIX, и в разных системах он работает по-разному.

## ЗАМЕЧАНИЯ
Вызов sigreturn() существует только для реализации обработчиков сигналов. Никогда не вызывайте его напрямую (на самом деле, простая обёртка sigreturn() в библиотеке GNU C просто вернёт -1 и присвоит errno значение ENOSYS). Содержимое аргументов (если есть), передаваемое sigreturn(), для каждой архитектуры своё (на некоторых архитектурах, например x86-64, у sigreturn() нет аргументов, так как вся требуемая информация доступна из кадра стека, который был создан ядром ранее в стеке пользовательского пространства).

Когда-то системы UNIX помещали код сигнального перехода в пользовательский стек. В настоящее время страницы пользовательского стека защищены и в них невозможно выполнить код. Поэтому в современных системах Linux, в зависимости от архитектуры, код хранится в vdso(7) или в библиотеке C. В последнем случае обёрточная функция sigaction(2) библиотеки C информирует ядро о расположении кода помещая его адрес в поле sa_restorer структуры sigaction и устанавливает флаг SA_RESTORER в поле sa_flags.

Сохранённая информация контекста процесса помещается в структуру ucontext_t (смотрите <sys/ucontext.h>). Эта структура видима внутри обработчика сигнала как третий аргумент обработчика, установленного sigaction(2) с флагом SA_SIGINFO.

В некоторых других системах UNIX работа сигнального батута несколько отличается. В частности, в некоторых системах при переходе в пользовательский режим ядро передаёт управление батуту (а не обработчику сигнала) и код батута вызывает обработчик сигнала (и затем вызывает sigreturn() после завершения работы обработчика).

### Отличия между библиотекой C и ядром
Первоначальное название системного вызова в Linux было sigreturn(). Однако с добавлением сигналов реального времени в Linux 2.2 для поддержки увеличенного типа sigset_t был добавлен новый системный вызов rt_sigreturn(). Библиотека GNU C скрывает это от нас, прозрачно используя rt_sigreturn(), если он есть в ядре.

## СМОТРИТЕ ТАКЖЕ
kill(2), restart_syscall(2), sigaltstack(2), signal(2), getcontext(3), signal(7), vdso(7)


sigsuspend

title: sigsuspend(2)

summary: ожидание сигнала

text:
# sigsuspend(2)

## ИМЯ
sigsuspend, rt_sigsuspend - ожидание сигнала

## ОБЗОР
\#include <signal.h>

int sigsuspend(const sigset_t *mask);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

sigsuspend(): _POSIX_C_SOURCE

## ОПИСАНИЕ
Вызов sigsuspend() временно заменяет маску сигналов вызывающей нити маской, указанной в mask, и затем приостанавливает нить до тех пор, пока не поступит сигнал, для которого запустится обработчик сигнала или это приведёт к завершению процесса.

Если по сигналу процесс завершается, то вызов sigsuspend() не возвращает управление обратно в программу. Если сигнал пойман, то возврат из sigsuspend() произойдёт после завершения выполнения обработчика, и маска сигналов восстановится в значение, которое было до вызова sigsuspend().

Сигналы SIGKILL и SIGSTOP невозможно заблокировать; указание этих этих сигналов в mask не влияет на маску сигналов нити.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Вызов sigsuspend() всегда возвращает -1; errno присваивается номер ошибки (обычно EINTR).

## ОШИБКИ
EFAULT

Аргумент mask указывает на память в недопустимой части адресного пространства процесса.

EINTR

Вызов был прерван по сигналу; смотрите signal(7).

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Обычно, sigsuspend() используется вместе с sigprocmask(2), чтобы предотвратить доставку сигнала при выполнении критического участка кода. Сначала вызывающий блокирует сигналы с помощью sigprocmask(2). Когда критический участок выполнен, вызывающий начинает ждать сигналов с помощью вызова sigsuspend(), указав маску, значение которой было возвращено вызовом sigprocmask(2) (в аргументе oldset).

Подробная информация о работе с наборами сигналов есть на странице sigsetops(3).

### Отличия между библиотекой C и ядром
Первоначально, системный вызов Linux назывался sigsuspend(). Однако, с добавлением сигналов реального времени в Linux 2.2, 32-битный аргумент sigset_t неизменяемого размера, поддерживаемый этим системным вызовом, не мог больше использоваться. В результате был добавлен новый системный вызов rt_sigsuspend() с увеличенным типом sigset_t. У нового системного вызова появился второй аргумент, size_t sigsetsize, в котором указывается размер (в байтах) набора сигналов mask. В настоящее время значение этого аргумента должно быть равно sizeof(sigset_t) (иначе возникает ошибка EINVAL). Обёрточная функция glibc sigsuspend() скрывает это и вызывает rt_sigsuspend(), если он есть в ядре.

## СМОТРИТЕ ТАКЖЕ
kill(2), pause(2), sigaction(2), signal(2), sigprocmask(2), sigwaitinfo(2), sigsetops(3), sigwait(3), signal(7)


sigwaitinfo

title: sigwaitinfo(2)

summary: синхронное ожидание запрошенных

text:
# sigwaitinfo(2)

## ИМЯ
sigwaitinfo, sigtimedwait, rt_sigtimedwait - синхронное ожидание запрошенных сигналов

## ОБЗОР

```
#include <signal.h>
```

```
int sigwaitinfo(const sigset_t *set, siginfo_t *info);
```

```
int sigtimedwait(const sigset_t *set, siginfo_t *info,
                 const struct timespec *timeout);
```

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

sigwaitinfo(), sigtimedwait(): _POSIX_C_SOURCE >= 199309L

## ОПИСАНИЕ
sigwaitinfo() приостанавливает исполнение вызывающий нити до тех пор, пока не будет ожидаться один из сигналов из набора set (если один из сигналов в set уже ожидает обработки вызывающей нитью, то sigwaitinfo() завершит работу немедленно с возвратом информации об этом сигнале).

sigwaitinfo() удаляет сигнал из списка сигналов ожидающих обработки и возвращает номер сигнала как результат работы функции. Если аргумент info не равен NULL, то в буфер, на который он указывает, записывается структура типа siginfo_t (см. sigaction(2)), содержащая информацию о сигнале.

Если в set ожидают обработки несколько сигналов, то сигнал, который получит sigwaitinfo(), определяется согласно обычным правилам очерёдности; подробней смотрите в signal(7).

Системный вызов sigtimedwait() работает аналогично sigwaitinfo(), за исключением того, что он имеет дополнительный аргумент timeout, задающий интервал, на который приостанавливается процесс в ожидании сигнала. Данное значение интервала будет округлено до точности системных часов, а из-за задержки при планировании в ядре блокирующий интервал будет немного больше. Этот аргумент имеет следующий тип:

```
struct timespec {

    long    tv_sec;         /* секунды */

    long    tv_nsec;        /* наносекунды */
}
```

Если оба поля структуры равны 0, то исполняется опрос: sigtimedwait() немедленно завершает работу, либо с информацией о сигнале, предназначенном вызывающему, либо с ошибкой, если ни один из сигналов в наборе set не ожидает обработки.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При нормальном завершении работы sigwaitinfo() и sigtimedwait() возвращают номер сигнала (т.е. значение больше нуля). При ошибках оба вызова возвращают -1 и переменная errno устанавливается соответственно ошибке.

## ОШИБКИ
EAGAIN

Ни одного сигнала в указанном наборе set не появилось для обработки за время timeout, указанном для sigtimedwait().

EINTR

Ожидание было прервано обработчиком сигнала; см. signal(7). (Этот обработчик был для другого сигнала, не из набора set.)

EINVAL

Значение timeout некорректно.

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
При обычном использовании вызывающая программа блокирует сигналы в наборе set через предыдущий вызов sigprocmask(2) (для того, чтобы не сработали обработчики по умолчанию этих сигналов, если они появятся для обработки между последующими вызовами sigwaitinfo() или sigtimedwait()) и не устанавливает обработчики для этих сигналов. В многонитевых программах сигнал должен быть заблокирован во всех нитях, чтобы предотвратить возврат сигнала нити, отличной от той, которая вызвала sigwaitinfo() или sigtimedwait()).

Набор сигналов, ожидающих обработки в заданной нити, представляет собой объединение набора сигналов, ожидающих обработки именно в этой нити и набора сигналов, ожидающих обработки всем процессом (см. signal(7)).

Попытки ожидания SIGKILL и SIGSTOP просто игнорируются.

Если несколько нитей процесса заблокированы в ожидании одного сигнала(ов) в sigwaitinfo() или sigtimedwait(), то только одна нить действительно получит сигнал, если он станет доступен для ожидания всему процессу; какая именно нить примет сигнал неизвестно.

Вызовы sigwaitinfo() и sigtimedwait() нельзя использовать для приёма сигналов, генерируемых синхронно, например сигнала SIGSEGV при доступе по неправильному адресу памяти, или сигнала SIGFPE при математических ошибках. Такие сигналы можно поймать только через обработчик сигнала.

POSIX оставляет неопределённое значение NULL в аргументе timeout для sigtimedwait(), допуская возможность того, что он имеет такое же значение, как и у вызова sigwaitinfo(), и в самом деле это именно так в Linux.

### Отличия между библиотекой C и ядром
В Linux, sigwaitinfo() реализована в виде библиотечной функции, использующей sigtimedwait().

Обёрточные функции glibc для sigwaitinfo() и sigtimedwait() просто игнорируют попытки ожидания двух сигналов реального времени, которые используются внутри реализации NPTL. Подробности смотрите в nptl(7).

Первоначально, системный вызов Linux назывался sigtimedwait(). Однако, с добавлением сигналов реального времени в Linux 2.2, 32-битный аргумент sigset_t неизменяемого размера, поддерживаемый этим системным вызовом, не мог больше использоваться. В результате был добавлен новый системный вызов rt_sigtimedwait() с увеличенным типом sigset_t. У нового системного вызова появился четвёртый аргумент, size_t sigsetsize, в котором указывается размер (в байтах) набора сигналов set. В настоящее время значение этого аргумента должно быть равно sizeof(sigset_t) (иначе возникает ошибка EINVAL). Обёрточная функция glibc sigtimedwait() скрывает это и вызывает rt_sigtimedwait(), если он есть в ядре.

## СМОТРИТЕ ТАКЖЕ
kill(2), sigaction(2), signal(2), signalfd(2), sigpending(2), sigprocmask(2), sigqueue(3), sigsetops(3), sigwait(3), signal(7), time(7)


socket

title: socket(2)

summary: создаёт конечную точку соединения

text:
# socket(2)

## ИМЯ
socket - создаёт конечную точку соединения

## ОБЗОР
\#include <sys/types.h> /* смотрите ЗАМЕЧАНИЯ */

\#include <sys/socket.h>

int socket(int domain, int type, int protocol);

## ОПИСАНИЕ
Системный вызов socket() создаёт конечную точку соединения и возвращает файловый дескриптор, указывающий на эту точку. Возвращаемый при успешном выполнении файловый дескриптор будет иметь самый маленький номер, который не используется процессом.

Параметр domain задает домен соединения: выбирает семейство протоколов, которое будет использоваться для соединения. Семейства описаны в <sys/socket.h>. В настоящее время ядром Linux распознаются следующие форматы:

Имя

Цель

Справочная страница

AF_UNIX

Локальное соединение

unix(7)

AF_LOCAL

Синоним AF_UNIX

AF_INET

Протоколы Интернет IPv4

ip(7)

AF_AX25

Протокол любительского радио AX.25

. ax25(4)

AF_IPX

Протоколы Novell IPX

AF_APPLETALK

AppleTalk

ddp(7)

AF_X25

Протокол ITU-T X.25/ISO-8208

x25(7)

AF_INET6

Протоколы Интернет IPv6

ipv6(7)

AF_DECnet

Протокольные сокеты DECet

AF_KEY

Протокол управления ключами, изначально разрабатывавшийся для использования с IPsec

AF_NETLINK

Устройство для взаимодействия с ядром

netlink(7)

AF_PACKET

Низкоуровневый пакетный интерфейс

packet(7)

AF_RDS

. Протокол надёжных датаграмных сокетов (RDS)

. . rds(7) rds-rdma(7)

AF_PPPOX

Транспортный слой PPP общего назначения для настройки туннелей L2 (L2TP и PPPoE)

AF_LLC

. Протокол управления логической связью (IEEE 802.2 LLC)

AF_IB

. Собственная адресация InfiniBand

AF_MPLS

. Многопротокольная коммутация по меткам

AF_CAN

. Протокол шины сети транспортных контроллеров

AF_TIPC

. Протокол «кластерных доменных сокетов» TIPC

AF_BLUETOOTH

. Сокетный протокол Bluetooth низкого уровня

AF_ALG

. Интерфейс к ядерному крипто-API

AF_VSOCK

. Протокол VSOCK (изначально «VMWare VSockets») для связей гипервизор-гость

vsock(7)

AF_KCM

. Интерфейс KCM (мультиплексор соединений ядра)

AF_XDP

. Интерфейс XDP (express data path)

Подробнее об адресных семействах, приведённых выше, а также информацию о других адресных семействах можно найти в address_families(7).

Сокет имеет тип type, задающий семантику соединения. В настоящее время определены следующие типы:

SOCK_STREAM

Обеспечивает создание двусторонних, надёжных потоков байтов на основе установления соединения. Может также поддерживаться механизм внепоточных данных.

SOCK_DGRAM

Поддерживает дейтаграммы (ненадежные сообщения с ограниченной длиной без установки соединения).

SOCK_SEQPACKET

Обеспечивает работу последовательного двустороннего канала для передачи дейтаграмм на основе соединений; дейтаграммы имеют постоянный размер; от получателя требуется за один раз прочитать целый пакет.

SOCK_RAW

Обеспечивает прямой доступ к сетевому протоколу.

SOCK_RDM

Обеспечивает надежную доставку дейтаграмм без гарантии, что они будут расположены по порядку.

SOCK_PACKET

Устарел и не должен использоваться в новых программах; см. packet(7).

Некоторые типы сокетов могут быть не реализованы во всех семействах протоколов.

Начиная с Linux 2.6.27, аргумент type предназначается для двух вещей: кроме определения типа сокета, для изменения поведения socket() он может содержать побитно сложенные любые следующие значения:

SOCK_NONBLOCK

Устанавливает флаг состояния файла O_NONBLOCK для нового открытого файлового описания (смотрите open(2)), на которое ссылается новый файловый дескриптор. Использование данного флага делает ненужными дополнительные вызовы fcntl(2) для достижения того же результата.

SOCK_CLOEXEC

Устанавливает флаг close-on-exec (FD_CLOEXEC) для нового открытого файлового дескриптора. Смотрите описание флага O_CLOEXEC в open(2) для того, чтобы узнать как это может пригодиться.

В protocol задаётся определённый протокол, используемый с сокетом. Обычно, только единственный протокол существует для поддержи определённого типа сокета с заданным семейством протоколов, в этом случае в protocol можно указать 0. Однако, может существовать несколько протоколов, тогда нужно указать один из них. Номер используемого протокола зависит от "домена соединения”, по которому устанавливается соединение; см. protocols(5). Смотрите getprotoent(3), где описано, как соотносить имена протоколов с их номерами.

Сокеты типа SOCK_STREAM являются соединениями полнодуплексных байтовых потоков. Они не сохраняют границы записей. Потоковый сокет должен быть в состоянии соединения перед тем, как из него можно будет отсылать данные или принимать их. Соединение с другим сокетом создается с помощью системного вызова connect(2). После соединения данные можно передавать с помощью системных вызовов read(2) и write(2) или одного из вариантов системных вызовов send(2) и recv(2). Когда сеанс закончен, выполняется команда close(2). Внепоточные данные могут передаваться, как описано в send(2), и приниматься, как описано в recv(2).

Протоколы связи, которые реализуют SOCK_STREAM, следят, чтобы данные не были потеряны или дублированы. Если часть данных, для которых имеется место в буфере протокола, не может быть передана за определённое время, соединение считается разорванным. Когда в сокете включен флаг SO_KEEPALIVE, протокол каким-либо способом проверяет, не отключена ли ещё другая сторона. Если процесс посылает или принимает данные, пользуясь «разорванным» потоком, ему выдаётся сигнал SIGPIPE; это приводит к тому, что процессы, не обрабатывающие этот сигнал, завершаются. Сокеты SOCK_SEQPACKET используют те же самые системные вызовы, что и сокеты SOCK_STREAM. Единственное отличие в том, что вызовы read(2) возвращают только запрошенное количество данных, а остальные данные пришедшего пакета будут отброшены. Границы сообщений во входящих дейтаграммах сохраняются.

Сокеты SOCK_DGRAM и SOCK_RAW позволяют посылать дейтаграммы принимающей стороне, заданной при вызове sendto(2). Дейтаграммы обычно принимаются с помощью вызова recvfrom(2), который возвращает следующую дейтаграмму с соответствующим обратным адресом.

Тип SOCK_PACKET считается устаревшим типом сокета; он позволяет получать необработанные пакеты прямо от драйвера устройства. Используйте вместо него packet(7).

Системный вызов fcntl(2) с аргументом F_SETOWN может использоваться для задания группы процессов, которая будет получать сигнал SIGURG, когда прибывают внепоточные данные, или сигнал SIGPIPE, когда соединение типа SOCK_STREAM неожиданно обрывается. Этот вызов также можно использовать, чтобы задать процесс или группу процессов, которые получают асинхронные уведомления о событиях ввода-вывода с помощью SIGIO. Использование F_SETOWN эквивалентно использованию вызова ioctl(2) с аргументом FIOSETOWN или SIOCSPGRP.

Когда сеть сообщает модулю протокола об ошибке (например, в случае IP, используя ICMP-сообщение), то для сокета устанавливается флаг ожидающей ошибки. Следующая операция этого сокета вернёт код ожидающей ошибки. Некоторые протоколы позволяют организовывать очередь ошибок в сокете для получения подробной информацию об ошибке; смотрите IP_RECVERR в ip(7).

Операции сокетов контролируются их параметрами options. Эти параметры описаны в <sys/socket.h>. Вызовы setsockopt(2) и getsockopt(2) используются, чтобы установить и получить необходимые параметры.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
В случае успешного выполнения возвращается дескриптор, ссылающийся на сокет. В случае ошибки возвращается -1, а значение errno устанавливается соответствующим образом.

## ОШИБКИ
EACCES

Нет прав на создание сокета указанного типа и/или протокола.

EAFNOSUPPORT

Реализация не поддерживает указанное семейства адресов.

EINVAL

Неизвестный протокол или недоступное семейство протоколов.

EINVAL

Неверные флаги в type.

EMFILE

Было достигнуто ограничение по количеству открытых файловых дескрипторов на процесс.

ENFILE

Достигнуто максимальное количество открытых файлов в системе.

ENOBUFS или ENOMEM

Недостаточно памяти для создания сокета. Сокет не может быть создан, пока не будет освобождено достаточное количество ресурсов.

EPROTONOSUPPORT

Тип протокола или указанный протокол не поддерживаются в этом домене.

Другие ошибки могут быть созданы модулями протоколов более низкого уровня.

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008, 4.4BSD.

Флаги SOCK_NONBLOCK и SOCK_CLOEXEC есть только в Linux.

Вызов socket() появился в 4.2BSD. Обычно он переносим в/из не-BSD систем на уровне сокетов BSD (включая варианты System V).

## ЗАМЕЧАНИЯ
В POSIX.1 не требуется включение <sys/types.h>, и этот заголовочный файл не требуется в Linux. Однако, для некоторых старых реализаций (BSD) требует данный файл, и в переносимых приложениях для предосторожности, вероятно, лучше его указать.

Для семейств протоколов в 4.x BSD используются константы PF_UNIX, PF_INET, PF_INET и т. д., тогда как AF_UNIX, AF_INET и т. п. используется для указания семейства адресов. Однако, в справочной странице BSD сказано: «Обычно, семейство протоколов совпадает с семейством адресов» и во всех последующих стандартах используется AF_*.

## ПРИМЕР
Пример использования socket() показан в getaddrinfo(3).

## СМОТРИТЕ ТАКЖЕ
accept(2), bind(2), close(2), connect(2), fcntl(2), getpeername(2), getsockname(2), getsockopt(2), ioctl(2), listen(2), read(2), recv(2), select(2), send(2), shutdown(2), socketpair(2), write(2), getprotoent(3), address_families(7), ip(7), socket(7), tcp(7), udp(7), unix(7)

“An Introductory 4.3BSD Interprocess Communication Tutorial” and “BSD Interprocess Communication Tutorial”, reprinted in UNIX Programmer's Supplementary Documents Volume 1.


socketcall

title: socketcall(2)

summary: системные вызовы сокетов

text:
# socketcall(2)

## ИМЯ
socketcall - системные вызовы сокетов

## ОБЗОР
\#include <linux/net.h>

int socketcall(int call, unsigned long *args);

## ОПИСАНИЕ
socketcall() — это общая точка входа в ядро всех системных вызовов сокетов. В аргументе call задаётся функция сокета, которая будет вызвана. Аргумент args указывает на блок параметров функции, которые передаются соответствующему вызову.

Пользовательские программы должны оперировать обычными функциями, имеющими стандартные имена. О существовании socketcall() необходимо знать лишь создателям стандартных библиотек и ядра.

Вызов

Справочная страница

SYS_SOCKET

socket(2)

SYS_BIND

bind(2)

SYS_CONNECT

connect(2)

SYS_LISTEN

listen(2)

SYS_ACCEPT

accept(2)

SYS_GETSOCKNAME

getsockname(2)

SYS_GETPEERNAME

getpeername(2)

SYS_SOCKETPAIR

socketpair(2)

SYS_SEND

send(2)

SYS_RECV

recv(2)

SYS_SENDTO

sendto(2)

SYS_RECVFROM

recvfrom(2)

SYS_SHUTDOWN

shutdown(2)

SYS_SETSOCKOPT

setsockopt(2)

SYS_GETSOCKOPT

getsockopt(2)

SYS_SENDMSG

sendmsg(2)

SYS_RECVMSG

recvmsg(2)

SYS_ACCEPT4

accept4(2)

SYS_RECVMMSG

recvmmsg(2)

SYS_SENDMMSG

sendmmsg(2)

## СООТВЕТСТВИЕ СТАНДАРТАМ
Эта функция есть только в Linux, и она не должна использоваться в переносимых программах.

## ЗАМЕЧАНИЯ
На некоторых архитектурах, например x86-64 и ARM, нет системного вызова socketcall(); вместо него реализованы системные вызовы socket(2), accept(2), bind(2) и т.д.

Для архитектуры x86-32, socketcall() исторически имел только одну точку входа в программном интерфейсе сокетов. Однако начиная с Linux 4.3, для x86-32 появились прямые системные вызовы в программном интерфейсе сокетов. for the sockets API. Это упрощает создание фильтров seccomp(2), которые отбирают системные вызовы сокетов (для новых пользовательских исполняемых файлов, которые компилируются с использованием новых точек входа), а также улучшают (совсем немного) производительность.

## СМОТРИТЕ ТАКЖЕ
accept(2), bind(2), connect(2), getpeername(2), getsockname(2), getsockopt(2), listen(2), recv(2), recvfrom(2), recvmsg(2), send(2), sendmsg(2), sendto(2), setsockopt(2), shutdown(2), socket(2), socketpair(2)


socketpair

title: socketpair(2)

summary: создает пару присоединённых сокетов

text:
# socketpair(2)

## ИМЯ
socketpair - создает пару присоединённых сокетов

## ОБЗОР
\#include <sys/types.h> /* смотрите ЗАМЕЧАНИЯ */

\#include <sys/socket.h>

int socketpair(int domain, int type, int protocol, int sv[2]);

## ОПИСАНИЕ
Вызов socketpair() создает пару неименованых присоединённых сокетов в заданном домене domain заданного типа type, используя (при необходимости) заданный протокол protocol. Подробнее об этих аргументах можно узнать в socket(2).

Файловые дескрипторы, используемые как ссылки на новые сокеты, возвращаются в sv[0] и sv[1]. Никаких различий между этими двумя сокетами нет.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении возвращается 0. В случае ошибки возвращается -1, errno устанавливается в соответствующее значение, а sv не изменяется.

В Linux (и других системах) socketpair() не изменяет sv при ошибке. Требование стандартизации этого поведения было добавлено в POSIX.1-2016.

## ОШИБКИ
EAFNOSUPPORT

Заданное семейство адресов не поддерживается в этой машине.

EFAULT

Адрес sv не ссылается на адресное пространство процесса.

EMFILE

Было достигнуто ограничение по количеству открытых файловых дескрипторов на процесс.

ENFILE

Достигнуто максимальное количество открытых файлов в системе.

EOPNOTSUPP

Заданный протокол не поддерживает создание пар сокетов.

EPROTONOSUPPORT

Заданный протокол не поддерживается на этой машине.

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008, 4.4BSD. Вызов socketpair() впервые появился в 4.2BSD. Обычно он переносим в/из не-BSD систем на уровне сокетов BSD (включая варианты System V).

## ЗАМЕЧАНИЯ
В Linux единственными поддерживаемыми доменами для этого вызова являются AF_UNIX (или его синоним AF_LOCAL) и AF_TIPC (начиная с Linux 4.12).

Начиная с Linux 2.6.27, в аргументе type вызова socketpair() поддерживаются флаги SOCK_NONBLOCK и SOCK_CLOEXEC, описанные в socket(2).

В POSIX.1 не требуется включение <sys/types.h>, и этот заголовочный файл не требуется в Linux. Однако, для некоторых старых реализаций (BSD) требует данный файл, и в переносимых приложениях для предосторожности, вероятно, лучше его указать.

## СМОТРИТЕ ТАКЖЕ
pipe(2), read(2), socket(2), write(2), socket(7), unix(7)


splice

title: splice(2)

text:
# splice(2)

## ИМЯ
splice - подключает данные к каналу/выбирает данные из канала

## ОБЗОР

```
#define _GNU_SOURCE         /* см. feature_test_macros(7) */
#include <fcntl.h>
```

```
ssize_t splice(int fd_in, loff_t *off_in, int fd_out,
               loff_t *off_out, size_t len, unsigned int flags);
```

## ОПИСАНИЕ
Вызов splice() перемещает данные между двумя файловыми дескрипторами не выполняя при этом копирование между адресным пространством пользователя и ядра. Он пересылает до len байт данных из файлового дескриптора fd_in в файловый дескриптор fd_out, где один из файловых дескрипторов должен ссылаться на канал.

К fd_in и off_in применяются следующие правила:

- Если fd_in указывает на канал, то значение off_in должно быть NULL.

- Если fd_in не указывает на канал и off_in равно NULL, то из fd_in читаются байты начиная с смещения файла и это смещение соответственно изменяется.

- Если fd_in не указывает на канал и off_in не равно NULL, то off_in должен указывать на буфер, в котором задаётся начальное смещение для чтения байтов из fd_in; в этом случае файловое смещение fd_in не изменяется.

Аналогичные правила относятся и к fd_out и off_out.

Аргумент flags представляет собой битовую маску, которая составляется логическим сложением (OR) следующих значений:

SPLICE_F_MOVE

Пытаться переместить страницы, а не копировать их. Используется только как подсказка ядру: страницы всё равно будут копироваться, если ядро не сможет переместить страницы из канала, или если буферы канала не ссылаются на полные страницы. Первая реализация этого флага была с дефектами: поэтому начиная с Linux 2.6.21 этот флаг ни на что не влияет (но по прежнему разрешён в вызове splice()); в будущем, возможно появится корректная реализация.

SPLICE_F_NONBLOCK

Не блокировать при вводе-выводе. Это делает операции соединения с каналом неблокируемыми, но splice(), тем не менее, может заблокироваться, так как файловые дескрипторы, с которыми ведётся работа, могут блокироваться (если у них не установлен флаг O_NONBLOCK).

SPLICE_F_MORE

В следующем подключении будут дополнительные данные. Полезно указывать, когда fd_out ссылается на сокет (смотрите также описание MSG_MORE в send(2) и описание TCP_CORK в tcp(7)).

SPLICE_F_GIFT

Не используется в splice(); смотрите vmsplice(2).

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении splice() возвращает количество байт, которые были записаны или получены из канала.

Возвращаемое значение 0 означает конец ввода. Если fd_in указывает на канал, то это означает, что нет данных для передачи и и блокировка не имела бы смысла, так как нет писателей, подключённых к пишущему концу канала.

В случае ошибки splice() возвращает -1, а errno устанавливается в соответствующее значение.

## ОШИБКИ
EAGAIN

В flags указан SPLICE_F_NONBLOCK или один из файловых дескрипторов был помечен как неблокирующий (O_NONBLOCK), и операция вызвала бы блокировку.

EBADF

Один или оба файловых дескриптора недействительны или в неправильном режиме чтения-записи.

EINVAL

Целевая файловая система не поддерживает подключение данных (splicing).

EINVAL

Файл назначения открыт в режиме добавления.

EINVAL

Ни один из файловых дескрипторов не ссылается на канал.

EINVAL

Указано смещение для устройства этого не поддерживающего (например, канала).

EINVAL

Значение fd_in и fd_out указывают на один и тот же канал.

ENOMEM

Не хватает памяти.

ESPIPE

Значение off_in или off_out не равно NULL, но соответствующий файловый дескриптор ссылается на канал.

## ВЕРСИИ
Системный вызов splice() впервые появился в Linux 2.6.17; поддержка в glibc добавлена в версии 2.5.

## СООТВЕТСТВИЕ СТАНДАРТАМ
Данный вызов есть только в Linux.

## ЗАМЕЧАНИЯ
Три системных вызова — splice(), vmsplice(2), and tee(2), предоставляют пользовательским программам полный контроль над произвольным буфером ядра; они реализованы в ядре на базе того же типа буферов, который используется для канала. Эти системные вызовы выполняют следующие задачи:

splice()

перемещает данные из буфера в произвольный файловый дескриптор или наоборот, и из одного буфера в другой.

tee(2)

«копирует» данные из одного буфера в другой.

vmsplice(2)

«копирует» данные из пользовательского пространства в буфер.

Хотя мы говорим о копировании, на самом деле копирования, обычно, не происходит. Ядро реализует канальный буфер как набор указателей со счётчиком ссылок на страницы памяти ядра. Ядро создаёт «копии» страниц в буфере посредством создания новых указателей (для выходного буфера), указывающих на страницы, и увеличивает счётчики ссылок страниц: копируются только указатели, а не страницы буфера.

В Linux 2.6.30 и старее, только один из fd_in и fd_out должен быть каналом. Начиная с Linux 2.6.31 оба параметра должны быть каналами.

## ПРИМЕР
См. tee(2).

## СМОТРИТЕ ТАКЖЕ
copy_file_range(2), sendfile(2), tee(2), vmsplice(2), pipe(7)


title: spu_create(2)

summary: создаёт новый контекст spu

text:
# spu_create(2)

## ИМЯ
spu_create - создаёт новый контекст spu

## ОБЗОР

```
#include <sys/types.h>
#include <sys/spu.h>
```

```
int spu_create(const char *pathname, int flags, mode_t mode);
int spu_create(const char *pathname, int flags, mode_t mode,
               int neighbor_fd);
```

Замечание: В glibc нет обёрточной функции для данного системного вызова; смотрите ЗАМЕЧАНИЯ.

## ОПИСАНИЕ
Системный вызов spu_create() используется на машинах PowerPC с архитектурой Cell Broadband Engine для получения доступа к Synergistic Processor Unit (SPU). Он создаёт новый логический контекст для SPU в pathname и возвращает связанный с ним файловый дескриптор. Аргумент pathname должен указывать на несуществующий каталог в точке монтирования файловой системы SPU (spufs). Если работа spu_create() выполнена без ошибок, то создаётся каталог pathname, а в нём создаются файлы, описанные в spufs(7).

После создания контекста, полученный файловый дескриптор может быть передан только spu_run(2), семейству системных вызовов *at (например, openat(2)) в аргументе dirfd или закрыт; другие операции не определены. Логический контекст SPU уничтожается (вместе с файлами, созданными внутри каталога контекста pathname) после освобождения последней ссылки на контекст; обычно, это происходит после закрытия файлового дескриптора, возвращённого spu_create().

Аргумент flags может быть равен нулю или содержать любую побитовую комбинацию (посредством OR) следующих констант:

SPU_CREATE_EVENTS_ENABLED

Вместо использования сигналов для сообщения об ошибках DMA, использовать аргумент event в spu_run(2).

SPU_CREATE_GANG

Создать блок (gang) SPU вместо контекста (блок — это группа контекстов SPU, которые близки по функциям и у которых общие параметры планирования — приоритет и политика. В будущем, планирование блока на включение и выключение может быть реализовано как единого целое).

В месте, указанном в аргументе pathname, будет создан новый каталог. Этот блок может использоваться для хранения других контекстов SPU, если указывать путь блока в последующих вызовах spu_create().

SPU_CREATE_NOSCHED

Создать контекст, на который не влияет планировщик SPU. После запуска контекста, он не будет планироваться для выполнения пока не будет уничтожен создавшим его процессом.

Так как контекст не может быть удалён из SPU, у контекстов SPU_CREATE_NOSCHED отключены некоторые возможности. Не все файлы будут доступны в каталоге этого контекста в spufs. Также, для контекстов SPU_CREATE_NOSCHED не может быть создан файл дампа при поломке.

Для создания контекстов SPU_CREATE_NOSCHED требуется мандат CAP_SYS_NICE.

SPU_CREATE_ISOLATE

Создать изолированный контекст SPU. Изолированные контексты защищены от некоторых операций PPE (PowerPC Processing Element), таких как доступ к локальному хранилищу SPU и регистру NPC.

Для создания контекста SPU_CREATE_ISOLATE также требуется флаг SPU_CREATE_NOSCHED.

SPU_CREATE_AFFINITY_SPU

Создать контекст со связью с другим контекстом SPU. Эта информация о связи используется в алгоритме планирования SPU. При использовании этого флага требуется, чтобы файловый дескриптор, ссылающийся на другой контекст SPU, передавался в аргументе neighbor_fd.

SPU_CREATE_AFFINITY_MEM

Создать контекст со связью с системной памятью. Эта информация о связи используется в алгоритме планирования SPU.

В аргументе mode (не считая битов umask(2) процесса) задаются права, которые используются при создании нового каталога в spufs. Полное описание всех значений mode смотрите в stat(2).

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

## ОШИБКИ
EACCES

Текущий пользователь не имеет прав на запись в точку монтирования spufs(7).

EEXIST

Контекст SPU с указанным именем пути уже существует.

EFAULT

Значение pathname не является допустимым строковым указателем в адресном пространстве вызывающего процесса.

EINVAL

Значение pathname не является каталогом в точке монтирования spufs(7), или указаны неправильные флаги.

ELOOP

Во время определения pathname встретилось слишком много символьных ссылок.

EMFILE

Было достигнуто ограничение по количеству открытых файловых дескрипторов на процесс.

ENAMETOOLONG

Слишком длинное значение аргумента pathname.

ENFILE

Достигнуто максимальное количество открытых файлов в системе.

ENODEV

Был запрошен изолированный контекст, но аппаратная часть не поддерживает изоляцию SPU.

ENOENT

Невозможно определить часть pathname.

ENOMEM

Ядро не может выделить все требуемые ресурсы.

ENOSPC

Недостаточно ресурсов SPU для создания нового контекста или достигнуто ограничение на количество контекстов SPU для пользователя.

ENOSYS

Возможность не предоставляется текущей системой, так как или аппаратура не предоставляет SPU, или не загружен модуль spufs.

ENOTDIR

Часть pathname не является каталогом.

EPERM

Указан флаг SPU_CREATE_NOSCHED, но пользователь не имеет мандата CAP_SYS_NICE.

## ФАЙЛЫ
Значение pathname должно указываться относительно точки монтирования spufs. По соглашению всё монтируется в /spu.

## ВЕРСИИ
Системный вызов spu_create() был добавлен в ядро Linux версии 2.6.16.

## СООТВЕТСТВИЕ СТАНДАРТАМ
Данный вызов существует только в Linux и реализован только для архитектуры PowerPC. Программы, использующие данный вызов, не переносимы.

## ЗАМЕЧАНИЯ
В glibc нет обёртки для этого системного вызова; запускайте его с помощью syscall(2). Однако заметим, что spu_run() предназначен для работы в библиотеках, которые реализуют более абстрактный интерфейс к SPU и не должен вызываться из обычных приложений. Рекомендуемые библиотеки приведены на странице http://www.bsc.es/projects/deepcomputing/linuxoncell/.

## ПРИМЕР
В spu_run(2) дан пример использования spu_create().

## СМОТРИТЕ ТАКЖЕ
close(2), spu_run(2), capabilities(7), spufs(7)


title: spu_run(2)

summary: выполняет контекст SPU

text:
# spu_run(2)

## ИМЯ
spu_run - выполняет контекст SPU

## ОБЗОР

```
#include <sys/spu.h>
```

```
int spu_run(int fd, unsigned int *npc, unsigned int *event);
```

Замечание: В glibc нет обёрточной функции для данного системного вызова; смотрите ЗАМЕЧАНИЯ.

## ОПИСАНИЕ
Системный вызов spu_run() используется на машинах PowerPC с архитектурой Cell Broadband Engine для получения доступа к Synergistic Processor Unit (SPU). Аргумент fd представляет собой файловый дескриптор, возвращаемый вызовом spu_create(2) и указывающий на определённый контекст SPU. Когда контекст планируется на физическом SPU, он запускается на выполнение начиная с инструкции, на которую указывает значение npc.

Выполнение кода SPU происходит синхронно, то есть spu_run() блокируется на время работы SPU. Если требуется параллельное выполнение кода SPU и кода на основном процессоре или других SPU, то сначала нужно создать новую нить выполнения (например с помощью pthread_create(3)).

При завершении работы spu_run() текущее значение программного счётчика SPU записывается в npc, что позволяет использовать тот же указатель npc в последующих вызовах spu_run().

В аргументе event указывается буфер для расширенного кода состояния. Если контекст SPU создан с флагом SPU_CREATE_EVENTS_ENABLED, то ядро Linux заполняет этот буфер перед возвратом из spu_run().

Код состояния может быть одной (или несколькими) из следующих констант:

SPE_EVENT_DMA_ALIGNMENT

Произошла ошибка выравнивания DMA.

SPE_EVENT_INVALID_DMA

Попытка выполнить неверную команду MFC DMA.

SPE_EVENT_SPE_DATA_STORAGE

Произошла ошибка хранилища DMA.

SPE_EVENT_SPE_ERROR

Выполнена недопустимая инструкция.

Для аргумента event допускается значение NULL. В этом случае информация о событиях не будет поступать в вызывающий процесс.

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

Значение регистра spu_status представляет собой битовую маску кодов состояния и необязательный 14-битный код, возвращаемый при выполнении инструкции stop-and-signal SPU. Битовые маски кодов состояний:

0x02

SPU остановлен инструкцией stop-and-signal.

0x04

SPU остановлен инструкцией halt.

0x08

SPU ожидает канала.

0x10

SPU в пошаговом режиме.

0x20

SPU пытался выполнить неверную инструкцию.

0x40

SPU пытался получить доступ к неверному каналу.

0x3fff0000

При наложении этой маски получается код, возвращаемый инструкцией stop-and-signal. Полученные биты корректны только, если установлен бит 0x02.

Если spu_run() не вернул ошибку, то один или более младших восьми битов всегда установлены.

## ОШИБКИ
EBADF

Значение fd не является правильным файловым дескриптором.

EFAULT

Задан неправильный указатель в npc или значение event не равно NULL и является неправильным указателем.

EINTR

При выполнении spu_run() получен сигнал; см. signal(7). При необходимости, значение npc обновляется до нового значения программного счётчика.

EINVAL

Значение fd не является правильным файловым дескриптором, возвращённым spu_create(2).

ENOMEM

Недостаточно памяти для обработки страничного сбоя в результате прямого доступа Memory Flow Controller (MFC).

ENOSYS

Возможность не предоставляется текущей системой, так как или аппаратура не предоставляет SPU, или не загружен модуль spufs.

## ВЕРСИИ
Системный вызов spu_run() был добавлен в ядро Linux версии 2.6.16.

## СООТВЕТСТВИЕ СТАНДАРТАМ
Данный вызов существует только в Linux и реализован только для архитектуры PowerPC. Программы, использующие данный вызов, не переносимы.

## ЗАМЕЧАНИЯ
В glibc нет обёртки для этого системного вызова; запускайте его с помощью syscall(2). Однако заметим, что spu_run() предназначен для работы в библиотеках, которые реализуют более абстрактный интерфейс к SPU и не должен вызываться из обычных приложений. Рекомендуемые библиотеки приведены на странице http://www.bsc.es/projects/deepcomputing/linuxoncell/.

## ПРИМЕР
В следующем примере реализована простая программа, состоящая из одной инструкции SPU и системного вызова spu_run().

```
#include <stdlib.h>
#include <stdint.h>
#include <unistd.h>
#include <stdio.h>
#include <sys/types.h>
#include <fcntl.h>
#define handle_error(msg) \

    do { perror(msg); exit(EXIT_FAILURE); } while (0)
int main(void)
{

    int context, fd, spu_status;

    uint32_t instruction, npc;

    context = spu_create("/spu/example-context", 0, 0755);

    if (context == -1)

        handle_error("spu_create");

    /* записать инструкцию 'stop 0x1234' в локальное хранилище

       памяти SPU

     */

    instruction = 0x00001234;

    fd = open("/spu/example-context/mem", O_RDWR);

    if (fd == -1)

        handle_error("open");

    write(fd, &instruction, sizeof(instruction));

    /* присвоить npc адрес начальной инструкции программы

     * SPU. Так как мы записали инструкцию в начало

     * файла mem, точка входа будет равна 0x0

     */

    npc = 0;

    spu_status = spu_run(context, &npc, NULL);

    if (spu_status == -1)

        handle_error("open");

    /* мы должны получить код состояния 0x1234002:

     *   0x00000002 (spu остановлен из-за stop-and-signal)

     * | 0x12340000 (код stop-and-signal)

     */

    printf("Состояние SPU: 0x%08x\n", spu_status);

    exit(EXIT_SUCCESS);
}
```

## СМОТРИТЕ ТАКЖЕ
close(2), spu_create(2), capabilities(7), spufs(7)


stat

title: stat(2)

summary: считывает состояние файла

text:
# stat(2)

## ИМЯ
stat, fstat, lstat, fstatat - считывает состояние файла

## ОБЗОР

```
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
```

```
int stat(const char *pathname, struct stat *statbuf);
int fstat(int fd, struct stat *statbuf);
int lstat(const char *pathname, struct stat *statbuf);
#include <fcntl.h>           /* определения констант AT_* */
#include <sys/stat.h>
```

```
int fstatat(int dirfd, const char *pathname, struct stat *statbuf,
            int flags);
```

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

lstat():

/* glibc 2.19 и старее */ _BSD_SOURCE

|| /* начиная с glibc 2.20 */ _DEFAULT_SOURCE

|| _XOPEN_SOURCE >= 500

|| /* начиная с glibc 2.10: */ _POSIX_C_SOURCE >= 200112L

fstatat():

Начиная с glibc 2.10:

_POSIX_C_SOURCE >= 200809L

До glibc 2.10:

_ATFILE_SOURCE

## ОПИСАНИЕ
Данные системные вызовы возвращают информацию о файле в буфер, на который указывает statbuf. Для этого не требуется иметь права доступа к самому файлу, но — в случае stat(), fstatat() и lstat() — потребуются права выполнения (поиска) на все каталоги, указанные в полном имени файла pathname.

Вызовы stat() и fstatat() возвращают информацию о файле, указанном в pathname; различия с fstatat() описаны далее.

Вызов lstat() идентичен stat(), но в случае, если pathname является символьной ссылкой, то возвращается информация о самой ссылке, а не о файле, на который она указывает.

Вызов fstat() идентичен stat(), но опрашиваемый файл задаётся в виде файлового дескриптора fd.

### Структура stat
Все эти системные вызовы возвращают структуру stat, которая содержит следующие поля:

```
struct stat {

    dev_t     st_dev;         /* ID устройства с файлом */

    ino_t     st_ino;         /* номер иноды */

    mode_t    st_mode;        /* тип файла и режим доступа */

    nlink_t   st_nlink;       /* количество жёстких ссылок */

    uid_t     st_uid;         /* идентификатор пользователя-владельца */

    gid_t     st_gid;         /* идентификатор группы-владельца */

    dev_t     st_rdev;        /* идентификатор устройства

                                 (для специального файла) */

    off_t     st_size;        /* общий размер в байтах */

    blksize_t st_blksize;     /* размер блока ввода-вывода файловой системы */

    blkcnt_t  st_blocks;      /* количество выделенных 512Б блоков */

    /* Начиная с Linux 2.6, ядро поддерживает точность до

       наносекунд в следующих полям меток времени.

       Подробней о версиях до Linux 2.6, смотрите ЗАМЕЧАНИЯ. */

    struct timespec st_atim;  /* время последнего доступа */

    struct timespec st_mtim;  /* время последнего изменения */

    struct timespec st_ctim;  /* время последней смены состояния */
#define st_atime st_atim.tv_sec      /* для обратной совместимости */
#define st_mtime st_mtim.tv_sec
#define st_ctime st_ctim.tv_sec
};
```

Замечание: порядок полей структуры stat для разных архитектур отличается. Также, в определении выше не показаны дополняющие байты, которые для различных архитектур могут присутствовать между некоторыми полями Если необходимы подробности, то посмотрите исходный код glibc и ядра.

Замечание: Для простоты и производительности различные поля структуры stat могут содержать информацию о состоянии из разных моментов работы системного вызова. Например, если st_mode или st_uid изменились другим процессом с помощью вызова chmod(2) или chown(2), то stat() может вернуть старое значение st_mode вместе с новым st_uid, или старое значение st_uid вместе с новым st_mode.

Поля структуры stat:

st_dev

Устройство, на котором расположен файл (для разбора идентификатора этого поля могут пригодиться макросы major(3) и minor(3)).

st_ino

Номер иноды файла.

st_mode

Тип файла и режим доступа. Дополнительную информацию смотрите в inode(7).

st_nlink

Количество жёстких ссылок на файл.

st_uid

Пользовательский идентификатор владельца файла.

st_gid

Групповой идентификатор владельца файла.

st_rdev

Устройство, который этот файл (инода) представляет.

st_size

Размер файла (если он обычный или является символьной ссылкой) в байтах. Размер символьной ссылки равен длине пути файла, на который она ссылается, без конечного нулевого байта.

st_blksize

«Предпочтительный» размер блока для эффективного ввода/вывода в файловой системе.

st_blocks

Количество блоков (по 512 байт), выделенных для файла (может быть меньше, чем st_size/512, когда в файле есть пропуски (holes)).

st_atime

Метка времени последнего доступа к файлу.

st_mtime

Метка времени последнего изменения файла.

st_ctime

Метка времени последнего изменения состояния файла.

Дополнительную информацию об этих полях смотрите в inode(7).

### fstatat()
Системный вызов fstatat() представляет собой обобщённый интерфейс доступа к файловой информации, и может выполнить работу за stat(), lstat() и fstat().

Если в pathname задан относительный путь, то он считается относительно каталога, на который ссылается файловый дескриптор dirfd (а не относительно текущего рабочего каталога вызывающего процесса, как это делается в stat() и lstat()).

Если в pathname задан относительный путь и значение dirfd равно AT_FDCWD, то pathname рассматривается относительно текущего рабочего каталога вызывающего процесса (как stat() и lstat()).

Если в pathname задан абсолютный путь, то dirfd игнорируется.

Значение flags может быть 0, или включать один или более следующих флагов:

AT_EMPTY_PATH (начиная с Linux 2.6.39)

Если значение pathname равно пустой строке, то выполнять действие над файлом, на который указывает dirfd (который может быть получен с помощью open(2) с флагом O_PATH). В этом случае dirfd может указывать на файл любого типа, а не только на каталог и поведение fstatat() подобно fstat(). Если dirfd равно AT_FDCWD, то вызов выполняет действие над текущим рабочим каталогом. Этот флаг есть только в Linux; для получения его определения определите _GNU_SOURCE.

AT_NO_AUTOMOUNT (начиная с Linux 2.6.38)

Не выполнять автоматическое монтирование конечного компонента («basename») pathname, если этот каталог является точкой автоматического монтирования. Это позволяет вызывающему получить атрибуты точки автоматического монтирования (а не расположения, где её предполагалось смонтировать). Начиная с Linux 4.14, также не создаётся несуществующее имя в каталоге по требованию, например в неявных картах автоматического монтировщика. Этот флаг можно использовать в инструментах, сканирующих каталоги, для предотвращения массового автоматического монтирования каталогов в их точки автоматического монтирования. Флаг AT_NO_AUTOMOUNT не учитывается, если к точке уже была выполнено монтирование. Этот флаг есть только Linux; для его получения нужно задать _GNU_SOURCE. Вызовы stat() и lstat() работают, как если бы был установлен флаг AT_NO_AUTOMOUNT.

AT_SYMLINK_NOFOLLOW

Если значение pathname является символьной ссылкой, не разыменовывать её, а вернуть информацию о самой ссылке, как это делается в lstat(). (По умолчанию, fstatat() разыменовывает символьные ссылки как и stat().)

Смотрите в openat(2) объяснение необходимости fstatat().

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

## ОШИБКИ
EACCES

Запрещён поиск в одном из каталогов пути pathname (смотрите также path_resolution(7)).

EBADF

Значение fd не является правильным открытым файловым дескриптором.

EFAULT

Неправильный адрес.

ELOOP

Во время определения пути встретилось слишком много символьных ссылок.

ENAMETOOLONG

Слишком длинное значение аргумента pathname.

ENOENT

Компонент пути pathname не существует или является повисшей символьной ссылкой.

ENOENT

Значение pathname равно пустой строке и в flags не указано значение AT_EMPTY_PATH.

ENOMEM

Не хватает памяти (например, памяти ядра).

ENOTDIR

Компонент в префиксе пути pathname не является каталогом.

EOVERFLOW

Значение pathname или fd ссылаются на файл, чей размер, номер inode или количество блоков не может быть представлено с помощью типов off_t, ino_t или blkcnt_t, соответственно. Эта ошибка может возникнуть, если, например, приложение собрано на 32-битной платформе без флага -D_FILE_OFFSET_BITS=64 при вызове stat() для файла, чей размер превышает (1<<31)-1 байт.

В fstatat() дополнительно могут возникнуть следующие ошибки:

EBADF

Значение dirfd не является правильным файловым дескриптором.

EINVAL

Указано неверное значение в flags.

ENOTDIR

Значение pathname содержит относительный путь и dirfd содержит файловый дескриптор, указывающий на файл, а не на каталог.

## ВЕРСИИ
Вызов fstatat() был добавлен в ядро Linux версии 2.6.16; поддержка в glibc доступна с версии 2.4.

## СООТВЕТСТВИЕ СТАНДАРТАМ
stat(), fstat(), lstat(): SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008.

fstatat(): POSIX.1-2008.

Согласно POSIX.1-2001, lstat() для символьной ссылки требует вернуть корректную информацию только в поле st_size и в типе файла в поле st_mode структуры stat. В POSIX.1-2008 более жёсткая спецификация, требующая, чтобы lstat() возвращал корректную информацию во всех полях кроме битов режима в st_mode.

Использование полей st_blocks и st_blksize может усложнить перенос на другие платформы. (Эти поля появились из BSD. Их смысл различается в разных системах и, вероятно, даже в одной системе при использовании NFS).

## ЗАМЕЧАНИЯ

### Поля с отметками времени
В старых ядрах и стандартах нет поддержки полей времени в наносекундах. Вместо них есть три поря времени — st_atime, st_mtime и st_ctime — с типом time_t, который имеет секундную точность.

Начиная с ядра 2.5.48, в структуре stat поддерживается наносекундная точность для всех трёх полей времени. Наносекундные компоненты каждой метки времени доступны под именами вида st_atim.tv_nsec, если определён подходящий макрос тестирования свойств. Наносекундные метки времени стандартизованы в POSIX.1-2008, и, начиная с версии 2.12, в glibc также есть поддержка имён наносекундных компонент, если определён _POSIX_C_SOURCE со значением 200809L или более, или _XOPEN_SOURCE со значением 700 или более. До glibc 2.19 включительно определения наносекундных компонент также доступны, если определён _BSD_SOURCE или _SVID_SOURCE. Если ни один из вышеупомянутых макросов не определён, то наносекундные значения доступны под именами вида st_atimensec.

### Отличия между библиотекой C и ядром
В течении долгого времени увеличение размера структуры stat привело к появлению трёх новых версий stat(): sys_stat() (слот __NR_oldstat), sys_newstat() (слот __NR_stat) и sys_stat64() (слот __NR_stat64) на 32-битных платформах, например, i386. Первые две версии уже существовали в Linux 1.0 (но под другими именами); последняя была добавлена в Linux 2.4. Подобное замечание применимо к fstat() и lstat().

Внутренние ядерные структуры stat в разных версиях:

__old_kernel_stat

Самая первая версия структуры со слегка узкими полями и без заполнителей.

stat

Увеличенное поле st_ino и добавлены заполнители в различные части структуры для расширения в дальнейшем.

stat64

Ещё раз увеличенное поле st_ino, увеличены поля st_uid и st_gid для работы с увеличенными в Linux-2.4 UID и GID до 32 бит, увеличены другие поля, дальнейшее добавление заполнителей в структуру (различные байты заполнения в дальнейшем были задействованы в Linux 2.6 с появлением 32-битных ID устройств и наносекундной части в полях временных отметок).

Обёрточная функция glibc stat() прячет эти подробности от приложений, вызывая самую новую версию системного вызова, предоставляемого ядром, и перепаковывая возвращаемую информацию, если это нужно для старых программ.

В современных 64-битных системах жизнь упростилась: единственный системный вызов stat() и ядро работает со структурой stat, в которой поля достаточного размера.

Нижележащий системный вызов, используемый обёрточной функцией fstatat() в glibc, на самом деле называется fstatat64() или, на некоторых архитектурах, newfstatat().

## ПРИМЕР
Следующая программа вызывает lstat() и показывает некоторые поля из полученной структуры stat.

```
#include <sys/types.h>
#include <sys/stat.h>
#include <time.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/sysmacros.h>
int
main(int argc, char *argv[])
{

    struct stat sb;

    if (argc != 2) {

        fprintf(stderr, "Использование: %s <путь>\n", argv[0]);

        exit(EXIT_FAILURE);

    }

    if (lstat(argv[1], &sb) == -1) {

        perror("lstat");

        exit(EXIT_FAILURE);

    }

    printf("ID содержащего устройства:  [%lx,%lx]\n",
	    (long) major(sb.st_dev), (long) minor(sb.st_dev));

    printf("Тип файла:                ");

    switch (sb.st_mode & S_IFMT) {

    case S_IFBLK:  printf("блочное устройство\n");     break;

    case S_IFCHR:  printf("символьное устройство\n");  break;

    case S_IFDIR:  printf("каталог\n");                break;

    case S_IFIFO:  printf("FIFO/канал\n");             break;

    case S_IFLNK:  printf("символьная ссылка\n");      break;

    case S_IFREG:  printf("обычный файл\n");           break;

    case S_IFSOCK: printf("сокет\n");                  break;

    default:       printf("неизвестно?\n");            break;

    }

    printf("номер inode:              %ld\n", (long) sb.st_ino);

    printf("Режим доступа:            %lo (octal)\n",

            (unsigned long) sb.st_mode);

    printf("Кол-во ссылок:            %ld\n", (long) sb.st_nlink);

    printf("Владелец:                 UID=%ld   GID=%ld\n",

            (long) sb.st_uid, (long) sb.st_gid);

    printf("Предпоч. размер бл. в/в:  %ld байт\n",

            (long) sb.st_blksize);

    printf("Размер файла:             %lld байт\n",

            (long long) sb.st_size);

    printf("Выделено блоков:          %lld\n",

            (long long) sb.st_blocks);

    printf("Посл. изм. состояния:     %s", ctime(&sb.st_ctime));

    printf("Посл. доступ к файлу:     %s", ctime(&sb.st_atime));

    printf("Посл. изм. файла:         %s", ctime(&sb.st_mtime));

    exit(EXIT_SUCCESS);
}
```

## СМОТРИТЕ ТАКЖЕ
ls(1), stat(1), access(2), chmod(2), chown(2), readlink(2), statx(2), utime(2), capabilities(7), inode(7), symlink(7)


statfs

title: statfs(2)

text:
# statfs(2)

## ИМЯ
statfs, fstatfs - возвращает статистику по файловой системе

## ОБЗОР
\#include <sys/vfs.h> /* или <sys/statfs.h> */

int statfs(const char *path, struct statfs *buf);

int fstatfs(int fd, struct statfs *buf);

## ОПИСАНИЕ
Системный вызов statfs() возвращает информацию о смонтированной файловой системе. Значение path является путём любого файла, расположенного в смонтированной файловой системе. Значение buf является указателем на структуру statfs, определённую, примерно, следующим образом:

```
struct statfs {

    __fsword_t f_type;    /* тип файловой системы (смотрите далее) */

    __fsword_t f_bsize;   /* оптимальный размер пересылаемых блоков */

    fsblkcnt_t f_blocks;  /* общее количество блоков данных

                             в файловой системе */

    fsblkcnt_t f_bfree;   /* свободных блоков в файловой системе */

    fsblkcnt_t f_bavail;  /* свободных блоков, доступных

                             непривилегированному пользователю */

    fsfilcnt_t f_files;   /* общее количество файловых нод

                             в файловой системе */

    fsfilcnt_t f_ffree;   /* свободных файловых нод в файловой системе */

    fsid_t     f_fsid;    /* ID файловой системы */

    __fsword_t f_namelen; /* максимальная длина имён файлов */

    __fsword_t f_frsize;  /* размер фрагмента (начиная с Linux 2.6) */

    __fsword_t f_flags;   /* флаги монтирования файловой системы

                             (начиная с Linux 2.6.36) */

    __fsword_t f_spare[xxx];

                    /* дополняющие байты, зарезервированные для будущего

                       использования */
};
```

В f_type могут быть указаны следующие типы файловых систем:

```
ADFS_SUPER_MAGIC      0xadf5
AFFS_SUPER_MAGIC      0xadff
AFS_SUPER_MAGIC       0x5346414f
ANON_INODE_FS_MAGIC   0x09041934 /* ФС анонимных инод (для

                                    псевдофайлов без имени;

                                    например, epoll, signalfd, bpf) */
AUTOFS_SUPER_MAGIC    0x0187
BDEVFS_MAGIC          0x62646576
BEFS_SUPER_MAGIC      0x42465331
BFS_MAGIC             0x1badface
BINFMTFS_MAGIC        0x42494e4d
BPF_FS_MAGIC          0xcafe4a11
BTRFS_SUPER_MAGIC     0x9123683e
BTRFS_TEST_MAGIC      0x73727279
CGROUP_SUPER_MAGIC    0x27e0eb   /* псевдофайловая система cgroup */
CGROUP2_SUPER_MAGIC   0x63677270 /* псевдофайловая система cgroup v2 */
CIFS_MAGIC_NUMBER     0xff534d42
CODA_SUPER_MAGIC      0x73757245
COH_SUPER_MAGIC       0x012ff7b7
CRAMFS_MAGIC          0x28cd3d45
DEBUGFS_MAGIC         0x64626720
DEVFS_SUPER_MAGIC     0x1373     /* Linux 2.6.17 и старее */
DEVPTS_SUPER_MAGIC    0x1cd1
ECRYPTFS_SUPER_MAGIC  0xf15f
EFIVARFS_MAGIC        0xde5e81e4
EFS_SUPER_MAGIC       0x00414a53
EXT_SUPER_MAGIC       0x137d     /* Linux 2.0 и старее */
EXT2_OLD_SUPER_MAGIC  0xef51
EXT2_SUPER_MAGIC      0xef53
EXT3_SUPER_MAGIC      0xef53
EXT4_SUPER_MAGIC      0xef53
F2FS_SUPER_MAGIC      0xf2f52010
FUSE_SUPER_MAGIC      0x65735546
FUTEXFS_SUPER_MAGIC   0xbad1dea  /* не используется */
HFS_SUPER_MAGIC       0x4244
HOSTFS_SUPER_MAGIC    0x00c0ffee
HPFS_SUPER_MAGIC      0xf995e849
HUGETLBFS_MAGIC       0x958458f6
ISOFS_SUPER_MAGIC     0x9660
JFFS2_SUPER_MAGIC     0x72b6
JFS_SUPER_MAGIC       0x3153464a
MINIX_SUPER_MAGIC     0x137f     /* первая ФС minix */
MINIX_SUPER_MAGIC2    0x138f     /* 30-символьная ФС minix */
MINIX2_SUPER_MAGIC    0x2468     /* ФС minix V2 */
MINIX2_SUPER_MAGIC2   0x2478     /* ФС minix V2, имена 30 символов */
MINIX3_SUPER_MAGIC    0x4d5a     /* ФС minix V3, имена 60 символов */
MQUEUE_MAGIC          0x19800202 /* ФС очереди сообщений POSIX */
MSDOS_SUPER_MAGIC     0x4d44
MTD_INODE_FS_MAGIC    0x11307854
NCP_SUPER_MAGIC       0x564c
NFS_SUPER_MAGIC       0x6969
NILFS_SUPER_MAGIC     0x3434
NSFS_MAGIC            0x6e736673
NTFS_SB_MAGIC         0x5346544e
OCFS2_SUPER_MAGIC     0x7461636f
OPENPROM_SUPER_MAGIC  0x9fa1
OVERLAYFS_SUPER_MAGIC 0x794c7630
PIPEFS_MAGIC          0x50495045
PROC_SUPER_MAGIC      0x9fa0     /* ФС /proc */
PSTOREFS_MAGIC        0x6165676c
QNX4_SUPER_MAGIC      0x002f
QNX6_SUPER_MAGIC      0x68191122
RAMFS_MAGIC           0x858458f6
REISERFS_SUPER_MAGIC  0x52654973
ROMFS_MAGIC           0x7275
SECURITYFS_MAGIC      0x73636673
SELINUX_MAGIC         0xf97cff8c
SMACK_MAGIC           0x43415d53
SMB_SUPER_MAGIC       0x517b
SOCKFS_MAGIC          0x534f434b
SQUASHFS_MAGIC        0x73717368
SYSFS_MAGIC           0x62656572
SYSV2_SUPER_MAGIC     0x012ff7b6
SYSV4_SUPER_MAGIC     0x012ff7b5
TMPFS_MAGIC           0x01021994
TRACEFS_MAGIC         0x74726163
UDF_SUPER_MAGIC       0x15013346
UFS_MAGIC             0x00011954
USBDEVICE_SUPER_MAGIC 0x9fa2
V9FS_MAGIC            0x01021997
VXFS_SUPER_MAGIC      0xa501fcf5
XENFS_SUPER_MAGIC     0xabba1974
XENIX_SUPER_MAGIC     0x012ff7b4
XFS_SUPER_MAGIC       0x58465342
_XIAFS_SUPER_MAGIC    0x012fd16d /* Linux 2.0 и старее */
```

Большинство этих констант MAGIC определены в /usr/include/linux/magic.h, а некоторые находятся прямо в исходном коде ядра.

Поле flags представляет собой битовую маску параметров монтирования файловой системы. В нём содержится ноль или несколько следующих бит:

ST_MANDLOCK

Разрешена обязательная (mandatory) блокировка файловой системы (смотрите fcntl(2)).

ST_NOATIME

Не обновлять времена доступа; смотрите mount(2).

ST_NODEV

Запретить доступ к специальным файлам устройств в этой файловой системе.

ST_NODIRATIME

Не обновлять времена доступа к каталогам; смотрите mount(2).

ST_NOEXEC

Исполнение программ в этой файловой системе запрещено.

ST_NOSUID

Биты set-user-ID и set-group-ID игнорируются в exec(3) для исполняемых файлов в этой файловой системе.

ST_RDONLY

Файловая система смонтирована в режиме только для чтения.

ST_RELATIME

Обновлять atime относительно mtime/ctime; смотрите mount(2).

ST_SYNCHRONOUS

Выполнять синхронную запись в файловую систему немедленно (смотрите описание O_SYNC в open(2)).

Значение f_fsid до конца не определено (но смотрите далее).

Если поле не определёно для какой-то файловой системы, то его значение устанавливается в 0.

fstatfs() возвращает такую же информацию об открытом файле через его ссылку на дескриптор fd.

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

## ОШИБКИ
EACCES

(statfs()) В одном из каталогов префикса пути path не разрешён поиск (см. также path_resolution(7)).

EBADF

(fstatfs()) fd не является корректным открытым дескриптором файла.

EFAULT

Аргумент buf или path указывает на неправильный адрес.

EINTR

Вызов был прерван каким-либо сигналом. Смотрите signal(7).

EIO

При чтении файловой системы произошла ошибка ввода-вывода.

ELOOP

(statfs()) Было обнаружено слишком много символьных ссылок при трансляции path.

ENAMETOOLONG

(statfs()) Слишком длинное значение аргумента path.

ENOENT

(statfs()) Файл, на который ссылается path, не существует.

ENOMEM

Недостаточное количество памяти ядра.

ENOSYS

Файловая система не поддерживает данный вызов.

ENOTDIR

(statfs()) Компонент в префиксе пути path не является каталогом.

EOVERFLOW

Некоторые значения слишком велики, чтобы быть представленными в возвращаемой структуре.

## СООТВЕТСТВИЕ СТАНДАРТАМ
Есть только в Linux. Вызов statfs() основан на подобном из 4.4BSD (но они используют разные структуры).

## ЗАМЕЧАНИЯ
Тип __fsword_t, используемый для различных полей в определении структуры statfs, является встроенным типом glibc и не предназначен для использования вовне. Это подкидывает загадку программисту, который хочет скопировать или сравнить эти поля с локальными переменными в программе. В большинстве систем для переменных в этих случаях допустимо использовать тип unsigned int.

Первые версии системных вызовов Linux statfs() и fstatfs() разрабатывались без учёта огромных размеров файлов. В последствии, в Linux 2.6 были добавлены системные вызовы statfs64() и fstatfs64(), в которых используется новая структура, statfs64. Новая структура содержит те же поля что и первоначальная структура statfs, но размеры некоторых полей были увеличены для учёта огромных размеров файлов. Обёрточные функции в glibc statfs() и fstatfs() прозрачно скрывают это различие ядер.

В одних системах есть только файл <sys/vfs.h>, в других также есть файл <sys/statfs.h>, при чём первый включает последний. Поэтому, вероятно, лучше включать первый.

В LSB библиотечные вызовы statfs() и fstatfs() помечены как устаревшие, вместе них предлагается использовать statvfs(2) и fstatvfs(2).

### Поле f_fsid
В Solaris, Irix и POSIX имеется системный вызов statvfs(2), который возвращает struct statvfs (определена в <sys/statvfs.h>), и в ней содержится поле unsigned long f_fsid. В Linux, SunOS, HP-UX, 4.4BSD имеется системный вызов statfs(), который возвращает struct statfs (определена в <sys/vfs.h>), и в ней содержится fsid_t f_fsid, где тип fsid_t определён как struct { int val[2]; }. Того же придерживается FreeBSD, за исключением того, что в ней используется включаемый файл <sys/mount.h>.

Общая идея в том, что в f_fsid содержится какая-то произвольная информация, например пара (f_fsid,ino) уникально определяющая файл. В некоторых операционных системах для этого используется номер устройства (один из вариантов) или номер устройства вместе с типом файловой системы. В других ОС поле f_fsid доступно только суперпользователю (и равно нулю для остальных пользователей), так как это поле используется в файловом указателе (filehandle) файловой системы при экспорте NFS, и выдача его значения влияет на безопасность.

В некоторых ОС fsid может использоваться в качестве второго аргумента системного вызова sysfs(2).

## ДЕФЕКТЫ
В Linux 2.6.38 и до Linux 3.1 включительно, вызов fstatfs() завершался с ошибкой ENOSYS для файловых дескрипторов, созданных с помощью pipe(2).

## СМОТРИТЕ ТАКЖЕ
stat(2), statvfs(3), path_resolution(7)


statx

title: statx(2)

text:
# statx(2)

## ИМЯ
statx - считывает состояние файла (расширенный вариант)

## ОБЗОР

```
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <fcntl.h>           /* константы AT_* */
```

```
int statx(int dirfd, const char *pathname, int flags,
          unsigned int mask, struct statx *statxbuf);
```

## ОПИСАНИЕ
Этот системный вызов возвращает информацию о файле, записывая её в буфер, на который указывает statxbuf. Возвращаемый буфер представляет собой структуру следующего вида:

```
struct statx {

    __u32 stx_mask;        /* маска битов, показывающая

                              заполненные поля */

    __u32 stx_blksize;     /* размер блока ввода-вывода файловой системы */

    __u64 stx_attributes;  /* индикаторы дополнительных файловых атрибутов */

    __u32 stx_nlink;       /* количество жёстких ссылок */

    __u32 stx_uid;         /* идентификатор пользователя-владельца */

    __u32 stx_gid;         /* идентификатор группы-владельца */

    __u16 stx_mode;        /* тип файла и режим доступа */

    __u64 stx_ino;         /* номер иноды */

    __u64 stx_size;        /* полный размер в байтах */

    __u64 stx_blocks;      /* количество выделенных 512-байтовых блоков */

    __u64 stx_attributes_mask;

                           /* маска, показывающая поддерживаемые атрибуты

                              в stx_attributes */

    /* поля меток времени */

    struct statx_timestamp stx_atime;  /* последний доступ */

    struct statx_timestamp stx_btime;  /* создание */

    struct statx_timestamp stx_ctime;  /* последнее изменение состояния */

    struct statx_timestamp stx_mtime;  /* последнее изменение */

    /* если файл представляет устройство, то в следующих

       полях содержится идентификатор устройства */

    __u32 stx_rdev_major;  /* основной идентификатор */

    __u32 stx_rdev_minor;  /* дополнительный идентификатор */

    /* поля идентификатора устройства с файловой системой,

       в которой содержится файл */

    __u32 stx_dev_major;   /* основной идентификатор */

    __u32 stx_dev_minor;   /* дополнительный идентификатор */
};
```

Метки времени файла хранятся в структуре следующего вида:

```
struct statx_timestamp {

    __s64 tv_sec;    /* количество секунд с начала Эпохи (время UNIX) */

    __u32 tv_nsec;   /* количество наносекунд, начиная с tv_sec */
};
```

(зарезервированное пространство и заполнители не показаны)

### При вызове statx():
Для получения состояния файла не требуется иметь права доступа к самому файлу, но в случае указания statx() с путём, потребуются права выполнения (поиска) во всех каталогах, указанных в полном имени файла pathname.

Вызов statx() для определения нужного файла использует pathname, dirfd и flags следующими путями:

Абсолютный путь

Если pathname начинается с косой черты, то целевой файла задан абсолютным путём. В этом случае значение dirfd игнорируется.

Относительный путь

Если pathname начинается не с косой черты и dirfd равно AT_FDCWD, то pathname рассматривается относительно текущего рабочего каталога процесса.

Путь, задаваемый относительно каталога

Если pathname начинается не с косой черты и dirfd содержит файловый дескриптор, указывающий на каталог, то pathname рассматривается относительно каталога, на который ссылается dirfd.

По файловому дескриптору

Если значение pathname равно пустой строке и в flags (смотрите ниже) указан флаг AT_EMPTY_PATH, то целевым файлом считается тот, на который указывает файловый дескриптор в dirfd.

Значение flags можно использовать для уточнения поиска на основе пути. Оно составляется из побитно слагаемых следующих констант:

AT_EMPTY_PATH

Если значение pathname равно пустой строке, то вызов выполняет действие с файлом, на который ссылается dirfd (может быть получен с помощью open(2) с флагом O_PATH). В этом случае dirfd может ссылаться на файл любого типа, а не только на каталог.

Если dirfd равно AT_FDCWD, то вызов использует текущий рабочий каталог.

Данный флаг существует только в Linux; для его получения определите _GNU_SOURCE.

AT_NO_AUTOMOUNT

Не выполнять автоматическое монтирование конечного компонента («basename») pathname, если это каталог, который является точкой монтирования. Это позволяет вызывающему получить атрибуты точки монтирования (а не расположения, где её предполагалось смонтировать). Этот флаг можно использовать в инструментах, сканирующих каталоги, для предотвращения массового автоматического монтирования каталогов в их точки монтирования. Флаг AT_NO_AUTOMOUNT не учитывается, если к точке уже уже была выполнено монтирование. Этот флаг есть только Linux; для его получения нужно задать _GNU_SOURCE.

AT_SYMLINK_NOFOLLOW

Если значение pathname является символьной ссылкой, не разыменовывать её, а выдать информацию о самой ссылке, подобно lstat(2).

Значение flags также может использоваться для контроля типа синхронизации, которое выполняет ядро при опросе файла на удалённой файловой системе. Оно составляется из побитно слагаемых следующих значений:

AT_STATX_SYNC_AS_STAT

Работать подобно stat(2). Используется по умолчанию и очень зависит от файловой системы.

AT_STATX_FORCE_SYNC

Принудительно синхронизировать атрибуты с сервером. Может потребовать от сетевой файловой системы выполнить запись данных для получения правильных меток времени.

AT_STATX_DONT_SYNC

Не выполнять синхронизацию, а использовать информацию из кэша (если есть). Это может означать, что полученная информация будет не точна, но в случае с сетевыми файловыми системами это позволяет не обращаться к серверу и даже может быть разрыв соединения.

Аргумент mask в statx() используется для указания ядру какие поля поля нужны вызывающему. Значение mask представляет побитовую комбинацию (посредством OR) следующих констант:

STATX_TYPE

Требуется stx_mode & S_IFMT

STATX_MODE

Требуется stx_mode & ~S_IFMT

STATX_NLINK

Требуется stx_nlink

STATX_UID

Требуется stx_uid

STATX_GID

Требуется stx_gid

STATX_ATIME

Требуется stx_atime

STATX_MTIME

Требуется stx_mtime

STATX_CTIME

Требуется stx_ctime

STATX_INO

Требуется stx_ino

STATX_SIZE

Требуется stx_size

STATX_BLOCKS

Требуется stx_blocks

STATX_BASIC_STATS

[всё вышеперечисленное]

STATX_BTIME

Требуется stx_btime

STATX_ALL

[все доступные в данный момент поля]

Заметим в общем, что ядро не не отклоняет значения в mask, отличные от вышеперечисленных (исключение из правила смотрите в описании ошибки EINVAL). Вместо этого оно просто информирует вызывающего, какие значения поддерживаются ядром и файловой системой через поле statx.stx_mask. Поэтому не устанавливайте значение mask в UINT_MAX (все биты), так как один или более бит в будущем могут использоваться для указания расширения буфера.

### Возвращаемая информация
Информация о состоянии целевого файла возвращается в структуре statx, на которую указывает statxbuf. Она содержит stx_mask, в котором описывается возвращённая информация. Значение stx_mask имеет тот же формат, что и аргумент mask, и установленные в нём бит показывают какие поля были заполнены.

Стоит упомянуть, что ядро может вернуть поля, которые не был запрошены и запрошенные поля могут быть не заполнены, в зависимости от поддержки в нижележащей файловой системе (поля, которым были присвоены значение, но которые не были запрошены, можно игнорировать). В этих случаях stx_mask будет не равно mask.

Если файловая система не поддерживает поле или если значение поле содержит непрезентабельное значение (например, файл экзотического типа), то битовая маска в stx_mask, соответствующая этому полю, будет очищена даже если пользователь запросил его, и в целях совместимости в качестве значения, если возможно, будет помещена пустышка (например, в некоторых случаях пустышки UID и GID могут задаваться при монтировании).

Файловая система также может заполнить поля, которые вызывающий не запрашивал, при условии, что их значения доступны и это ничего стоит. Если это выполняется, то будут установлены соответствующие биты в stx_mask.

Замечание: с целью производительности и простоты различные поля в структуре statx могут содержать информацию о состоянии из различных моментов выполнения системного вызова. Например, если изменяется stx_mode или stx_uid другим процессом посредством вызова chmod(2) или chown(2), то stat() может вернуть старое значение stx_mode вместе с новым stx_uid, или старое stx_uid вместе с новым stx_mode.

Помимо полей stx_mask (описанной выше) структура statx имеет следующие поля:

stx_blksize

«Предпочтительный» размер блока для эффективного ввода/вывода в файловой системе (запись в файл более мелкими порциями может привести к неэффективному чтению/изменению/повторной записи).

stx_attributes

Дополнительная информация о состоянии файла (подробности ниже).

stx_nlink

Количество жёстких ссылок на файл.

stx_uid

Пользовательский идентификатор владельца файла.

stx_gid

Групповой идентификатор владельца файла.

stx_mode

Тип файла и режим. Дополнительную информацию смотрите в inode(7).

stx_ino

Номер иноды файла.

stx_size

Размер файла (если он обычный или является символьной ссылкой) в байтах. Размер символьной ссылки равен длине пути файла, на который она ссылается, без конечного нулевого байта.

stx_blocks

Количество блоков (по 512 байт), выделенных для файла на носителе (может быть меньше, чем stx_size/512, когда в файле есть пропуски (holes)).

stx_attributes_mask

Маска, показывающая какие биты в stx_attributes поддерживаются VFS и файловой системой.

stx_atime

Метка времени последнего доступа к файлу.

stx_btime

Метка времени создания файла.

stx_ctime

Метка времени последнего изменения состояния файла.

stx_mtime

Метка времени последнего изменения файла.

stx_dev_major и stx_dev_minor

Устройство, на котором находится файл (инода).

stx_rdev_major и stx_rdev_minor

Устройство, который этот файл (инода) представляет, если файл имеет блочный или символьный тип устройства.

Дополнительную информацию об этих полях смотрите в inode(7).

### Атрибуты файла
В поле stx_attributes содержится набор флагов (объединённых через ИЛИ), которые отображают дополнительные атрибуты файла. Заметим, что для атрибута, не указанного как поддерживаемого в stx_attributes_mask, имеющееся здесь значение является не корректным. Биты stx_attributes_mask точно бит в бит соответствуют битам поля stx_attributes.

Флаги:

STATX_ATTR_COMPRESSED

Файл сжат файловой системой и для доступа могут потребоваться дополнительные ресурсы.

STATX_ATTR_IMMUTABLE

Файл невозможно изменить: его нельзя переименовать или удалить, на этот файл нельзя создать жёсткую ссылку и в него нельзя выполнить запись данных. Смотрите chattr(1).

STATX_ATTR_APPEND

Файл может быть открыт только для записи в режиме добавления. Запись в произвольное место не разрешается. Смотрите chattr(1).

STATX_ATTR_NODUMP

Файл не предназначен для резервного копирования программой резервного копирования, например dump(8). Смотрите chattr(1).

STATX_ATTR_ENCRYPTED

Для расшифровки файла файловой системой требуется ключ.

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

## ОШИБКИ
EACCES

Запрещён поиск в одном из каталогов пути pathname (смотрите также path_resolution(7)).

EBADF

Значение dirfd не является правильным открытым файловым дескриптором.

EFAULT

Значение pathname или statxbuf равно NULL или указывает на расположение вне доступного процессу адресного пространства.

EINVAL

Указано неверное значение в flags.

EINVAL

В mask указан зарезервированный флаг (в настоящее время есть только один флаг, для него определена константа STATX__RESERVED со значением 0x80000000U).

ELOOP

Во время определения пути встретилось слишком много символьных ссылок.

ENAMETOOLONG

Слишком длинное значение аргумента pathname.

ENOENT

Компонент пути pathname не существует или в pathname указана пустая строка и в flags не указан AT_EMPTY_PATH.

ENOMEM

Не хватает памяти (например, памяти ядра).

ENOTDIR

Компонент префикса пути pathname содержит относительный путь и dirfd содержит файловый дескриптор, указывающий на файл, а не на каталог.

## ВЕРСИИ
Вызов statx() был добавлен в Linux 4.11; поддержка в glibc доступна с версии 2.28.

## СООТВЕТСТВИЕ СТАНДАРТАМ
Вызов statx() есть только в Linux.

## СМОТРИТЕ ТАКЖЕ
ls(1), stat(1), access(2), chmod(2), chown(2), readlink(2), stat(2), utime(2), capabilities(7), inode(7), symlink(7)


stime

title: stime(2)

summary: устанавливает системное время

text:
# stime(2)

## ИМЯ
stime - устанавливает системное время

## ОБЗОР
\#include <time.h>

int stime(const time_t *t);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

stime():

начиная с glibc 2.19:

_DEFAULT_SOURCE

glibc 2.19 и старее:

_SVID_SOURCE

## ОПИСАНИЕ
Вызов stime() устанавливает системное (не аппаратное) время и дату машины. Время, заданное в t, измеряется в секундах с начала Эпохи, с 00:00:00 1 января 1970 года (UTC). Функцию stime() может вызывать только суперпользователь.

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

## ОШИБКИ
EFAULT

Ошибка при получении информации из пространства пользователя.

EPERM

Вызвавшему процессу не хватает прав. В Linux для этого требуется мандат CAP_SYS_TIME.

## СООТВЕТСТВИЕ СТАНДАРТАМ
SVr4.

## СМОТРИТЕ ТАКЖЕ
date(1), settimeofday(2), capabilities(7)