ИМЯ

shm_open, shm_unlink - создаёт/открывает или удаляет объекты общей памяти POSIX

ОБЗОР

#include <sys/mman.h> #include <sys/stat.h> /* константы для mode */ #include <fcntl.h> /* константы O_* */

int shm_open(const char *name, int oflag, mode_t mode);

int shm_unlink(const char *name);

Компонуется при указании параметра -lrt.

ОПИСАНИЕ

Функция shm_open() создаёт и открывает новый (или открывает уже существующий) объект общей памяти POSIX. Объект общей памяти POSIX — это описатель, используемый несвязанными процессами для выполнения mmap(2) для одной области общей памяти. Функция shm_unlink() выполняет обратную операцию, удаляя объект, созданный ранее с помощью shm_open().

Действие shm_open() аналогично open(2). Значением name определяется создаваемый или открываемый объект общей памяти. Для использования в переносимых программах объект общей памяти должен опознаваться по имени в виде /какое_то_имя, то есть строкой, оканчивающейся null и длиной до NAME_MAX (т.е., 255) символов, состоящей из начальной косой черты и одного или более символов (любых, кроме косой черты).

Аргумент oflag содержит маску битов, созданную логическим сложением OR одного из флагов O_RDONLY или O_RWDR и любых других флагов, перечисленных далее:

O_RDONLY

Открыть объект для чтения. Открытый таким образом объект общей памяти можно указывать в mmap(2) только для чтения (PROT_READ).

O_RDWR

Открыть объект для чтения и записи.

O_CREAT

Создать объект общей памяти, если он не существует. Владелец и группа объекта устанавливаются из соответствующих эффективных ID вызвавшего процесса, а биты прав на объект устанавливаются в соответствии с младшими 9 битами mode, за исключением того, что биты, установленные маске режима создания файла (см. umask(2)), очищаются у новых объектов. Набор макросов-констант, используемых для определения mode, описан в open(2). Символические определения этих констант можно получить включением <sys/stat.h>.

Новый объект общей памяти изначально имеет нулевую длину; размер объекта можно установить, используя ftruncate(2). Новые выделенные байты объекта общей памяти автоматически заполняются 0.

O_EXCL

Если также был указан O_CREAT и объект общей памяти с заданным name уже существует, то возвращается ошибка. Проверка существования объекта и его создание, если он не существует, выполняется атомарно.

O_TRUNC

Если объект общей памяти уже существует, то обрезать его до 0 байтов.

Определения значений этих флагов можно получить включением <fcntl.h>.

При успешном выполнении shm_open() возвращает новый файловый дескриптор, ссылающийся на объект общей памяти. Этот файловый дескриптор гарантированно будет дескриптором файла с самым маленьким номером среди ещё не открытых процессом. У дескриптора файла устанавливается флаг FD_CLOEXEC (см. fcntl(2)).

Дескриптор файла обычно используется в последующих вызовах ftruncate(2) (для новых объектов) и mmap(2). После вызова mmap(2) дескриптор файла может быть закрыт без влияния на отображение памяти.

Действие shm_unlink() аналогично unlink(2): оно удаляет имя объекта общей памяти и, как только все процессы завершили работу с объектом и отменили его отображение, очищает пространство и уничтожает связанную с ним область памяти. После успешного выполнения shm_unlink() попытка выполнить shm_open() для объекта с тем же именем name завершается ошибкой (если не был указан O_CREAT, в этом случае создаётся новый, уже другой объект).

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

При успешном выполнении shm_open() возвращает неотрицательный дескриптор файла. При ошибках shm_open() возвращает -1. При успешном выполнении shm_unlink() возвращает 0 и -1 при ошибке.

ОШИБКИ

При ошибках в errno записываются причины ошибки. Значения errno могут быть такими:

EACCES

Отказ в доступе для shm_unlink() для объекта общей памяти.

EACCES

Отказ в доступе для shm_open() с заданным name и режимом mode, или был указан O_TRUNC, а вызывающий не имеет прав на запись для объекта.

EEXIST

В shm_open() указаны O_CREAT и O_EXCL, но объект общей памяти name уже существует.

EINVAL

Аргумент name для shm_open() некорректен.

EMFILE

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

ENAMETOOLONG

Длина name превышает PATH_MAX.

ENFILE

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

ENOENT

Была сделана попытка выполнить shm_open() для несуществующего name и при этом не был указан O_CREAT.

ENOENT

Была сделана попытка выполнить shm_unlink() для несуществующего name.

ВЕРСИИ

Эти функции присутствуют в glibc 2.2 и более новых.

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

СООТВЕТСТВИЕ СТАНДАРТАМ

POSIX.1-2001, POSIX.1-2008.

В POSIX.1-2001 сказано, что группа-владелец нового объекта общей памяти устанавливается или в эффективный ID группы вызвавшего процесса, или «ID системной группы по умолчанию». В POSIX.1-2008 сказано, что группа-владелец может быть установлена или в эффективный ID группы вызвавшего процесса или, если объект видим в файловой системе, ID группы родительского каталога.

ЗАМЕЧАНИЯ

POSIX оставляет неопределённым поведение при комбинации O_RDONLY и O_TRUNC. В Linux это приводит к успешному обрезанию существующего объекта общей памяти, но в других системах UNIX может быть по-другому.

Реализация объектов общей памяти POSIX в Linux использует выделенную файловую систему tmpfs(5), которая обычно монтируется в /dev/shm.

СМОТРИТЕ ТАКЖЕ

close(2), fchmod(2), fchown(2), fcntl(2), fstat(2), ftruncate(2), memfd_create(2), mmap(2), open(2), umask(2), shm_overview(7)