memfd_create(2)

НАИМЕНОВАНИЕ
memfd_create - создаёт анонимный файл

БИБЛИОТЕКА
Стандартная библиотека языка C (libc, -lc)

СИНТАКСИС
#define _GNU_SOURCE         /* Смотрите feature_test_macros(7) */
#include <sys/mman.h>

int memfd_create(const char *name, unsigned int flags);

ОПИСАНИЕ
Вызов memfd_create() создаёт анонимный файл и возвращает ссылающийся на него файловый дескриптор. Анонимный файл ведёт себя как обычный файл и может быть изменён, обрезан, отображён в память и т.д. Однако в отличие от обычного файла он располагается в ОЗУ и не имеет энергонезависимого хранилища. Как только все ссылки на файл удаляются, он автоматически исчезает. Анонимные файлы располагаются в анонимной памяти. Поэтому у файлов, создаваемых memfd_create(), такая же семантика как и областей анонимной памяти, выделяемой с помощью mmap(2) с флагом MAP_ANONYMOUS.

Первоначально, размер файла равен 0. После этого вызова нужно задать размер файла с помощью ftruncate(2) (или заполнить файл с помощью write(2) или подобными).

Имя, указанное в name, используется в качестве имени файла и будет показываться как цель соответствующей символьной ссылки в каталоге. /proc/self/fd/. Отображаемое имя всегда начинается с memfd: и служит только для отладки. Имена не влияют на поведение файлового дескриптора и поэтому несколько файлов могут иметь одно имя без каких-либо последствий.

Для изменения поведения memfd_create() можно использовать следующие значения flags (через OR):

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

MFD_ALLOW_SEALING
    Разрешает операции опечатывания (sealing) файла. Описание операций F_ADD_SEALS и F_GET_SEALS смотрите в fcntl(2), а также в ЗАМЕЧАНИЯ ниже. Первоначально набор печатей пуст. Если этот флаг не установлен, то начальным набором печатей будет F_SEAL_SEAL, означающий запрещение установки печатей на файл.

MFD_HUGETLB (начиная с Linux 4.14)
    В файловой системе hugetlbfs, использующей огромные страницы, будет создан анонимный файл. В файле исходного кода Linux Documentation/admin-guide/mm/hugetlbpage.rst дана подробная информация о hugetlbfs. Одновременное указание MFD_HUGETLB и MFD_ALLOW_SEALING в flags поддерживается начиная с Linux 4.16.

MFD_HUGE_2MB
MFD_HUGE_1GB
...
    Используется как дополнение к MFD_HUGETLB для выбора размера страницы hugetlb (соответственно, 2 МБ, 1 ГБ, …) в системах, которые поддерживают различные размеры страниц hugetlb. Определения размеров огромных страниц включены в заголовочный файл <linux/memfd.h>.

    Дополнительную информацию о кодировании размеров огромных страниц, отсутствующих в заголовочном файле, смотрите в описании сходных по имени констант в mmap(2).

Неиспользуемые биты в flags должны быть равны 0.

В качестве возвращаемого значения memfd_create() возвращает новый файловый дескриптор, который можно использовать для обращения к файлу. Данный файловый дескриптор открыт на чтение и запись (O_RDWR) и в файловом дескрипторе установлен флаг O_LARGEFILE.

При вызове fork(2) и execve(2) с файловым дескриптором, созданным memfd_create(), применяется обычная семантика. Копия файлового дескриптора наследуется потомком, созданным fork(2), указывает на тот же файл. Файловый дескриптор сохраняется при после execve(2), если не установлен флаг close-on-exec.

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

ОШИБКИ

EFAULT
    Некорректный адрес в name.

EINVAL
    В flags указаны неизвестные биты.

EINVAL
    Значение name было слишком длинным (ограничено 249 байтами, не считая конечный байт null).

EINVAL
    В flags указаны MFD_HUGETLB и MFD_ALLOW_SEALING одновременно.

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

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

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

EPERM
    The MFD_HUGETLB flag was specified, but the caller was not privileged (did not have the CAP_IPC_LOCK capability) and is not a member of the hugetlb_shm_group group; see the description of /proc/sys/vm/hugetlb_shm_group in proc_sys_vm(5).

СТАНДАРТЫ
Linux.

ИСТОРИЯ
Linux 3.17, glibc 2.27.

ПРИМЕЧАНИЯ
Системный вызов memfd_create() предоставляет простую альтернативу ручному монтированию файловой системы tmpfs(5), созданию и открытию файла в этой файловой системе. Основным предназначением memfd_create() является создание файлов и соответствующих файловых дескрипторов, которые используются с программным интерфейсом опечатывания файлов, предоставляемым fcntl(2).

Системный вызов memfd_create() также используется и без опечатывания файла (вот почему опечатывание файлов отключено, если этого не запросить явно с помощью флага MFD_ALLOW_SEALING). В частности, он может использоваться как альтернатива созданию файлов в tmp или использованию open(2) с O_TMPFILE в случаях, когда не требуется реальная ссылка на конечный файл в файловой системе.

  Опечатывание файла (file sealing)
Ели файл не опечатан, то процессы, которые связываются через общую память, должны или доверять друг другу, или учитывать возможность того, что недоверенная сторона может работать с общей памятью проблемным способом. Например, недоверенная сторона может изменить содержимое общей памяти в любое время или уменьшить область общей памяти. Первая возможность делает локальный процесс уязвимым к состязательности условий «момент проверки — момент использования» (обычно решается копированием данных из области общей памяти перед проверкой и использованием). Последняя возможность делает локальный процесс уязвимым к сигналам SIGBUS, которые возникают при попытке получить доступ к теперь несуществующему расположению в области общей памяти (решается использованием обработчика сигнала SIGBUS).

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

В примере использования механизма опечатывания происходит следующее:

(1) Первый процесс создаёт файл tmpfs(5) с помощью memfd_create(). Вызов возвращает файловый дескриптор, используемый далее.

(2) Первый процесс задаёт размер файла, созданного ранее, с помощью ftruncate(2), отображает его с помощью mmap(2) и заполняется общую память нужными данными.

(3) The first process uses the fcntl(2) F_ADD_SEALS operation to place one or more seals on the file, in order to restrict further modifications on the file. (If placing the seal F_SEAL_WRITE, then it will be necessary to first unmap the shared writable mapping created in the previous step. Otherwise, behavior similar to F_SEAL_WRITE can be achieved by using F_SEAL_FUTURE_WRITE, which will prevent future writes via mmap(2) and write(2) from succeeding while keeping existing shared writable mappings).

(4) Второй процесс получает файловый дескриптор файла tmpfs(5) и отображает его. Варианты того, как это можно сделать:

    •   Процесс, вызвавший memfd_create(), может переслать полученный файловый дескриптор второму процессу через доменный сокет UNIX (смотрите unix(7) и cmsg(3)). Второй процесс затем отображает файл с помощью mmap(2).

    •   Второй процесс создаётся с помощью fork(2) и, таким образом, наследует файловый дескриптор и отображение (заметим, что в этом случае и следующем образуется природное доверие между двумя процессами, так как они работают с правами одного пользовательского идентификатора. Поэтому опечатывание файла здесь не нужно).

    •   The second process opens the file /proc/pid/fd/fd, where <pid> is the PID of the first process (the one that called memfd_create()), and <fd> is the number of the file descriptor returned by the call to memfd_create() in that process. The second process then maps the file using mmap(2).

(5) Второй процесс использует fcntl(2) с операцией F_GET_SEALS для получения битовой маски печатей, которые были применены к файлу. Данная маска проверяется, чтобы определить какие ограничения наложены на изменения файла. Если требуется, то второй процесс может наложить дополнительные печати, что ещё ограничить действия (возможно до тех пор, пока не будет наложена печать F_SEAL_SEAL).

ПРИМЕРЫ
Далее показано два примера программы, в которых продемонстрировано использование memfd_create() и программный интерфейс опечатывания файла.

Первая программа, t_memfd_create.c, создаёт файл tmpfs(5) с помощью memfd_create(), изменяет его размер, отображает в память и, возможно, накладывает несколько печатей на файл. Программа принимает не более трёх аргументов командной строки, два первых обязательные. Первым аргументом задаётся имя файла, во втором — размер файла, а в необязательном третьем — строка символов, задающих устанавливаемые печати на файл.

Вторая программа, t_get_seals.c, может использоваться для открытия существующего файла, созданного memfd_create(), и проверки набора печатей, применённых к файлу.

Следующий пример сеанса показывает как использовать программу. Сначала создаётся файл tmpfs(5) и накладываются печати:

    $ ./t_memfd_create my_memfd_file 4096 sw &
    [1] 11775
    PID: 11775; fd: 3; /proc/11775/fd/3

После этого программа t_memfd_create продолжает выполняться в фоновом режиме. Из другой программы можно получить дескриптор файла, созданный memfd_create(), открыв файл /proc/pid/fd, который соответствует файловому дескриптору, открытому memfd_create(). Используя это имя, можно просмотреть содержимое символьной ссылки /proc/pid/fd и использовать программу t_get_seals для просмотра печатей, которые установлены на файл:

    $ readlink /proc/11775/fd/3;
    /memfd:my_memfd_file (deleted)
    $ ./t_get_seals /proc/11775/fd/3;
    Existing seals: WRITE SHRINK

  Исходный код программы: t_memfd_create.c
    #define _GNU_SOURCE
    #include <err.h>
    #include <fcntl.h>
    #include <stdint.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <sys/mman.h>
    #include <sys/types.h>
    #include <unistd.h>

    int
    main(int argc, char *argv[])
    {
        int           fd;
        char          *name, *seals_arg;
        ssize_t       size;
        unsigned int  seals;

        if (argc < 3) {
            fprintf(stderr, "%s name size [seals]\n", argv[0]);
            fprintf(stderr, "\t'seals' can contain any of the "
                    "following characters:\n");
            fprintf(stderr, "\t\tg - F_SEAL_GROW\n");
            fprintf(stderr, "\t\ts - F_SEAL_SHRINK\n");
            fprintf(stderr, "\t\tw - F_SEAL_WRITE\n");
            fprintf(stderr, "\t\tW - F_SEAL_FUTURE_WRITE\n");
            fprintf(stderr, "\t\tS - F_SEAL_SEAL\n");
            exit(EXIT_FAILURE);
        }

        name = argv[1];
        size = atoi(argv[2]);
        seals_arg = argv[3];

        /* Create an anonymous file in tmpfs; allow seals to be
           placed on the file.  */

        fd = memfd_create(name, MFD_ALLOW_SEALING);
        if (fd == -1)
            err(EXIT_FAILURE, "memfd_create");

        /* Size the file as specified on the command line.  */

        if (ftruncate(fd, size) == -1)
            err(EXIT_FAILURE, "truncate");

        printf("PID: %jd; fd: %d; /proc/%jd/fd/%d\n",
               (intmax_t) getpid(), fd, (intmax_t) getpid(), fd);

        /* Code to map the file and populate the mapping with data
           omitted.  */

        /* If a 'seals' command-line argument was supplied, set some
           seals on the file.  */

        if (seals_arg != NULL) {
            seals = 0;

            if (strchr(seals_arg, 'g') != NULL)
                seals |= F_SEAL_GROW;
            if (strchr(seals_arg, 's') != NULL)
                seals |= F_SEAL_SHRINK;
            if (strchr(seals_arg, 'w') != NULL)
                seals |= F_SEAL_WRITE;
            if (strchr(seals_arg, 'W') != NULL)
                seals |= F_SEAL_FUTURE_WRITE;
            if (strchr(seals_arg, 'S') != NULL)
                seals |= F_SEAL_SEAL;

            if (fcntl(fd, F_ADD_SEALS, seals) == -1)
                err(EXIT_FAILURE, "fcntl");
        }

        /* Keep running, so that the file created by memfd_create()
           continues to exist.  */

        pause();

        exit(EXIT_SUCCESS);
    }

  Исходный код программы: t_get_seals.c
    #define _GNU_SOURCE
    #include <err.h>
    #include <fcntl.h>
    #include <stdio.h>
    #include <stdlib.h>

    int
    main(int argc, char *argv[])
    {
        int           fd;
        unsigned int  seals;

        if (argc != 2) {
            fprintf(stderr, "%s /proc/PID/fd/FD\n", argv[0]);
            exit(EXIT_FAILURE);
        }

        fd = open(argv[1], O_RDWR);
        if (fd == -1)
            err(EXIT_FAILURE, "open");

        seals = fcntl(fd, F_GET_SEALS);
        if (seals == -1)
            err(EXIT_FAILURE, "fcntl");

        printf("Existing seals:");
        if (seals & F_SEAL_SEAL)
            printf(" SEAL");
        if (seals & F_SEAL_GROW)
            printf(" GROW");
        if (seals & F_SEAL_WRITE)
            printf(" WRITE");
        if (seals & F_SEAL_FUTURE_WRITE)
            printf(" FUTURE_WRITE");
        if (seals & F_SEAL_SHRINK)
            printf(" SHRINK");
        printf("\n");

        /* Code to map the file and access the contents of the
           resulting mapping omitted.  */

        exit(EXIT_SUCCESS);
    }

СМОТРИТЕ ТАКЖЕ
fcntl(2), ftruncate(2), memfd_secret(2), mmap(2), shmget(2), shm_open(3)

ПЕРЕВОД
Русский перевод этой страницы руководства разработал(и) aereiae <aereiae@gmail.com>, Alexey <a.chepugov@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitriy S. Seregin <dseregin@59.ru>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, ITriskTI <ITriskTI@gmail.com>, Max Is <ismax799@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Иван Павлов <pavia00@gmail.com> и Малянов Евгений Викторович <maljanow@outlook.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков (debian-l10n-russian@lists.debian.org).