ИМЯ¶

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:

sem_perm

This is an ipc_perm structure (see below) that specifies the access permissions on the semaphore set.

sem_otime

Время последнего системного вызова semop(2).

sem_ctime

Time of creation of semaphore set or time of last semctl() IPCSET, SETVAL, or SETALL operation.

sem_nsems

Число семафоров в наборе. Каждый семафор описывается неотрицательным целым числом от 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:

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

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

IPC_STAT

Копирует информацию из структуры данных ядра, связанной с semid, в структуру semid_ds, расположенную по адресу arg.buf. Аргумент semnum игнорируется. Вызывающий процесс должен иметь права на чтение набора семафоров.

IPC_SET

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.

IPC_RMID

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

IPC_INFO (есть только в Linux)

Возвращает параметры и информацию о системных ограничениях семафоров в структуре, указанной в 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).

SEM_INFO (есть только в Linux)

Возвращает структуру seminfo, содержащую такую же информацию что и для IPC_INFO, за исключением того, что следующие поля содержат информацию о системных ресурсах, потребляемых семафорами: в поле semusz возвращается количество наборов семафоров, существующих в системе; в поле semaem возвращается общее количество семафоров во всех наборах семафоров в системе.

SEM_STAT (есть только в Linux)

Возвращает структуру semid_ds как для IPC_STAT. Однако аргумент semid содержит не идентификатор семафора, а индекс во внутреннем массиве ядра, который хранит информацию о всех наборах семафоров в системе.

SEM_STAT_ANY (есть только в Linux-specific, начиная с Linux 4.17)

Возвращает структуру seminfo, содержащую информацию как у SEM_STAT. Однако sem_perm.mode не проверяется на доступность чтения для semid, что означает, что эту операцию может выполнять пользователь (как и любой пользователь, который может прочитать эту же информацию из /proc/sysvipc/sem).

GETALL

Возвращает значение semval (т.е. текущее значение) всех семафоров в наборе в arg.array. Аргумент semnum игнорируется. Вызывающему процессу нужны права на чтение набора семафоров.

GETNCNT

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.

GETPID

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.

GETVAL

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.

GETZCNT

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.

SETALL

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.

SETVAL

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:

GETNCNT

значение semncnt.

GETPID

значение sempid.

GETVAL

значение semval.

GETZCNT

значение semzcnt.

IPC_INFO

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

SEM_INFO

как для IPC_INFO.

SEM_STAT

идентификатор набора семафоров, индекс которого указан в semid.

SEM_STAT_ANY

как у SEM_STAT.

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

ОШИБКИ¶

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

EACCES

Аргумент cmd равен GETALL, GETPID, GETVAL, GETNCNT, GETZCNT, IPC_STAT, SEM_STAT, SEM_STAT_ANY, SETALL или SETVAL и вызывающий процесс не имеет требуемых прав на набор семафоров и не имеет мандата CAP_IPC_OWNER в пользовательском пространстве имён, которое управляет своим пространством имён IPC.

EFAULT

Адрес, указанный в arg.buf или arg.array, недоступен.

EIDRM

Набор семафоров был удалён.

EINVAL

Неверное значение cmd или semid. Или: при операции SEM_STAT значение индекса, указанное в semid, ссылается на место в массиве, которое в данные момент не используется.

EPERM

Аргумент cmd имеет значение IPC_SET или IPC_RMID, но эффективный идентификатор пользователя вызывающего процесса не совпадает с ID создателя (указанного в sem_perm.cuid) или с ID владельца (указанного в sem_perm.uid) набора семафоров, и процесс не имеет мандата CAP_SYS_ADMIN.

ERANGE

Аргумент 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() влияет системное ограничение:

SEMVMX

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

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

ПРИМЕРЫ¶

Смотрите 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.