Scroll to navigation

SEMCTL(2) Руководство программиста Linux SEMCTL(2)

ИМЯ

semctl - операции управления семафорами System V

СИНТАКСИС

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semctl(int semid, int semnum, int cmd, ...);

ОПИСАНИЕ

Вызов semctl выполняет операцию, определённую в cmd, над набором семафоров System V, указанном в semid, или над семафором с номером semnum из этого набора (семафоры нумеруются, начиная с 0).

Данный вызов имеет три или четыре аргумента, в зависимости от значения cmd. Если аргументов четыре, то четвертый аргумент arg имеет тип union semun. В вызывающей программе это объединение должно быть определено следующим образом:


union semun {

int val; /* значение для SETVAL */
struct semid_ds *buf; /* буфер для IPC_STAT, IPC_SET */
unsigned short *array; /* массив для GETALL, SETALL */
struct seminfo *__buf; /* буфер для IPC_INFO
(есть только в Linux) */ };

Структура данных semid_ds определена в <sys/sem.h> следующим образом:


struct semid_ds {

struct ipc_perm sem_perm; /* Ownership and permissions */
time_t sem_otime; /* Last semop time */
time_t sem_ctime; /* Creation time/time of last
modification via semctl() */
unsigned long sem_nsems; /* No. of semaphores in set */ };

The fields of the semid_ds structure are as follows:

This is an ipc_perm structure (see below) that specifies the access permissions on the semaphore set.
Время последнего системного вызова semop(2).
Time of creation of semaphore set or time of last semctl() IPCSET, SETVAL, or SETALL operation.
Число семафоров в наборе. Каждый семафор описывается неотрицательным целым числом от 0 до sem_nsems-1.

Структура ipc_perm определена следующим образом (значения полей устанавливаются с помощью IPC_SET):


struct ipc_perm {

key_t __key; /* ключ, передаваемый в semget(2) */
uid_t uid; /* эффективный UID владельца */
gid_t gid; /* эффективный GID владельца */
uid_t cuid; /* эффективный UID создателя */
gid_t cgid; /* эффективный GID создателя */
unsigned short mode; /* права */
unsigned short __seq; /* порядковый номер */ };

The least significant 9 bits of the mode field of the ipc_perm structure define the access permissions for the shared memory segment. The permission bits are as follows:

0400 Read by user
0200 Write by user
0040 Read by group
0020 Write by group
0004 Read by others
0002 Write by others

In effect, "write" means "alter" for a semaphore set. Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.

Возможные значения cmd:

Копирует информацию из структуры данных ядра, связанной с semid, в структуру semid_ds, расположенную по адресу arg.buf. Аргумент semnum игнорируется. Вызывающий процесс должен иметь права на чтение набора семафоров.
Write the values of some members of the semid_ds structure pointed to by arg.buf to the kernel data structure associated with this semaphore set, updating also its sem_ctime member.
The following members of the structure are updated: sem_perm.uid, sem_perm.gid, and (the least significant 9 bits of) sem_perm.mode.
The effective UID of the calling process must match the owner (sem_perm.uid) or creator (sem_perm.cuid) of the semaphore set, or the caller must be privileged. The argument semnum is ignored.
Немедленно удаляет набор семафоров, пробуждая все процессы, заблокированные в вызове semop(2) (при этом возвращается сообщение об ошибке, а errno присваивается значение EIDRM). Эффективный идентификатор пользователя вызывающего процесса должен совпадать с идентификатором создателя или владельца набора семафоров, или вызывающий должен иметь расширенные права. Аргумент semnum игнорируется.
Возвращает параметры и информацию о системных ограничениях семафоров в структуре, указанной в arg.__buf. Данная структура имеет тип seminfo, который определён в <sys/sem.h>, если определён макрос тестирования свойств _GNU_SOURCE:

struct  seminfo {

int semmap; /* количество записей в карте
семафоров; не используется в ядре */
int semmni; /* максимальное количество наборов
семафоров */
int semmns; /* максимальное количество семафоров во
всех наборах семафоров */
int semmnu; /* максимальное количество структур undo
в системе; не используется в ядре */
int semmsl; /* максимальное количество семафоров в
наборе */
int semopm; /* максимальное количество операция для
semop(2) */
int semume; /* максимальное количество записей undo на
процесс; не используется в ядре */
int semusz; /* размер struct sem_undo */
int semvmx; /* максимальное значение семафора */
int semaem; /* максимальное значение, которое может
быть записано для регулирования
семафора (SEM_UNDO) */ };

Значения semmsl, semmns, semopm и semmni можно изменить через /proc/sys/kernel/sem; подробности в proc(5).
Возвращает структуру seminfo, содержащую такую же информацию что и для IPC_INFO, за исключением того, что следующие поля содержат информацию о системных ресурсах, потребляемых семафорами: в поле semusz возвращается количество наборов семафоров, существующих в системе; в поле semaem возвращается общее количество семафоров во всех наборах семафоров в системе.
Возвращает структуру semid_ds как для IPC_STAT. Однако аргумент semid содержит не идентификатор семафора, а индекс во внутреннем массиве ядра, который хранит информацию о всех наборах семафоров в системе.
Возвращает структуру seminfo, содержащую информацию как у SEM_STAT. Однако sem_perm.mode не проверяется на доступность чтения для semid, что означает, что эту операцию может выполнять пользователь (как и любой пользователь, который может прочитать эту же информацию из /proc/sysvipc/sem).
Возвращает значение semval (т.е. текущее значение) всех семафоров в наборе в arg.array. Аргумент semnum игнорируется. Вызывающему процессу нужны права на чтение набора семафоров.
Return the semncnt value for the semnum-th semaphore of the set (i.e., the number of processes waiting for the semaphore's value to increase). The calling process must have read permission on the semaphore set.
Return the sempid value for the semnum-th semaphore of the set. This is the PID of the process that last performed an operation on that semaphore (but see NOTES). The calling process must have read permission on the semaphore set.
Return semval (i.e., the semaphore value) for the semnum-th semaphore of the set. The calling process must have read permission on the semaphore set.
Return the semzcnt value for the semnum-th semaphore of the set (i.e., the number of processes waiting for the semaphore value to become 0). The calling process must have read permission on the semaphore set.
Set the semval values for all semaphores of the set using arg.array, updating also the sem_ctime member of the semid_ds structure associated with the set. Undo entries (see semop(2)) are cleared for altered semaphores in all processes. If the changes to semaphore values would permit blocked semop(2) calls in other processes to proceed, then those processes are woken up. The argument semnum is ignored. The calling process must have alter (write) permission on the semaphore set.
Set the semaphore value (semval) to arg.val for the semnum-th semaphore of the set, updating also the sem_ctime member of the semid_ds structure associated with the set. Undo entries are cleared for altered semaphores in all processes. If the changes to semaphore values would permit blocked semop(2) calls in other processes to proceed, then those processes are woken up. The calling process must have alter permission on the semaphore set.

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

При ошибке semctl() возвращает -1, а переменной errno присваивается номер ошибки.

При успешном выполнении системный вызов возвращает положительное значение, зависящее от cmd:

значение semncnt.
значение sempid.
значение semval.
значение semzcnt.
самое большое значение индекса, использованного в записи внутреннего массива ядра, содержащего информацию о всех наборах семафоров (эта информация может использоваться в повторяющихся операциях SEM_STAT или SEM_STAT_ANY для получения информации о всех наборах семафоров в системе).
как для IPC_INFO.
идентификатор набора семафоров, индекс которого указан в semid.
как у SEM_STAT.

Для всех остальных значений cmd возвращается 0.

ОШИБКИ

При ошибке errno присваиваются следующие значения:

Аргумент cmd равен GETALL, GETPID, GETVAL, GETNCNT, GETZCNT, IPC_STAT, SEM_STAT, SEM_STAT_ANY, SETALL или SETVAL и вызывающий процесс не имеет требуемых прав на набор семафоров и не имеет мандата CAP_IPC_OWNER в пользовательском пространстве имён, которое управляет своим пространством имён IPC.
Адрес, указанный в arg.buf или arg.array, недоступен.
Набор семафоров был удалён.
Неверное значение cmd или semid. Или: при операции SEM_STAT значение индекса, указанное в semid, ссылается на место в массиве, которое в данные момент не используется.
Аргумент cmd имеет значение IPC_SET или IPC_RMID, но эффективный идентификатор пользователя вызывающего процесса не совпадает с ID создателя (указанного в sem_perm.cuid) или с ID владельца (указанного в sem_perm.uid) набора семафоров, и процесс не имеет мандата CAP_SYS_ADMIN.
Аргумент cmd имеет значение SETALL или SETVAL и значение, присваиваемое semval (для какого-то семафора в наборе), меньше нуля или больше, чем ограничение реализации SEMVMX.

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

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

В POSIX.1 указано, что поле sem_nsems структуры semid_ds имеет тип unsigned short, и это так на в большинстве других систем. Это было и в Linux 2.2 и более ранних версиях, но начиная с Linux 2.4 это поле имеет тип unsigned long.

ЗАМЕЧАНИЯ

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

Операции IPC_INFO, SEM_STAT и SEM_INFO используются программой ipcs(1) для получения информации о выделенных ресурсах. В будущем для этого может быть задействован интерфейс файловой системы /proc.

В Linux 2.2 различные поля struct semid_ds имели тип short. В Linux 2.4 тип был изменён на long. Для задействования преимуществ этого изменения необходима перекомпиляция программы с glibc-2.1.91 или более поздней версией (ядро различает старые и новые вызовы по флагу IPC_64 в аргументе cmd).

В некоторых ранних версиях glibc объединение semun определялось в <sys/sem.h>, но в POSIX.1 требовалось, чтобы это объединение определял вызывающий. В версиях glibc, в которых это объединение не определено, в <sys/sem.h> определён макрос _SEM_SEMUN_UNDEFINED.

На работу наборов семафоров и вызова semctl() влияет системное ограничение:

Максимальное значение semval: зависит от реализации (32767).

Для лучшей переносимости программ желательно всегда вызывать semctl() c четырьмя аргументам.

Значение sempid

В POSIX.1 значение sempid определено как «ID процесса последней операции» над семафором, и явно отмечено, что это значение устанавливается успешным вызовом semop(2), подразумевая, что больше никто не изменяет sempid.

Одни реализации следуют требованиям, указанным в POSIX.1, а другие нет (вина здесь, вероятно, лежит на POSIX.1, так как ему не удастся охватить поведение всех существующих реализаций). Также, разные реализации обновляют sempid другими операциями, обновляющими значение семафора: SETVAL и SETALL, а также изменение семафора, выполняемое при завершении процесса как следствие использования флага SEM_UNDO (смотрите semop(2)).

Linux also updates sempid for SETVAL operations and semaphore adjustments. However, somewhat inconsistently, up to and including Linux 4.5, the kernel did not update sempid for SETALL operations. This was rectified in Linux 4.6.

ПРИМЕРЫ

Смотрите shmop(2).

СМ. ТАКЖЕ

ipc(2), semget(2), semop(2), capabilities(7), sem_overview(7), sysvipc(7)

ЗАМЕЧАНИЯ

Эта страница является частью проекта Linux man-pages версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу https://www.kernel.org/doc/man-pages/.

ПЕРЕВОД

Русский перевод этой страницы руководства был сделан Alexander Golubev <fatzer2@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Hotellook, Nikita <zxcvbnm3230@mail.ru>, Spiros Georgaras <sng@hellug.gr>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

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

21 декабря 2020 г. Linux