semctl - производит операции управления семафорами

НАЗВАНИЕ
semctl - производит операции управления семафорами

СИНТАКСИС
#include
#include
#include

int semctl(int semid, int semnum, int cmd, ...);

ОПИСАНИЕ
Функция semctl позволяет выполнять операции, определенные
в cmd над набором семафоров, указанным в semid или над
семафором с номером semnum из этого набора. (Семафоры
нумеруются начиная с 0.)

Функция имеет три или четыре аргумента. Если аргументов
четыре, то вызов выглядит как semctl(semid,sem-
num,cmd,arg); где четвертый аргумент arg имеет тип union
semun, определенный как

/* union semun is defined by including */
/* according to X/OPEN we have to define it ourselves */
union semun {
int val; /* value for SETVAL */
struct semid_ds *buf; /* buffer for IPC_STAT, IPC_SET */
unsigned short *array; /* array for GETALL, SETALL */
/* Linux specific part: */
struct seminfo *__buf; /* buffer for IPC_INFO */
};

Аргумент cmd может принимать следующие значения:

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

IPC_SET Внесите значения некоторых членов структуры
semid_ds, на которую указывает arg.buf , в
структуру данных набора семафоров и обновите
sem_ctime. Присвоить следующим полям
структуры данных struct semid_ds
соответствующие значения, на которые указывает
arg.buf

sem_perm.uid
sem_perm.gid
sem_perm.mode /* Только младшие 9 битов */

Эта команда может выполняться только
процессом, который имеет действующий
идентификатор пользователя, равный либо
идентификатору суперпользователя, либо
создателя или владельца набора семафоров.
Аргумент semnum игнорируется.

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

GETALL Возвращает значение semval всем семафорам в
массиве arg.array. Аргумент semnum
игнорируется. Для этого вызывающему процессу
нужны права на чтение.

GETNCNT Системный вызов возвращает значение semncnt
семафору semnum-th (например, число процессов,
ожидающих увеличения значения semval семафора
semnum-th). Для этого вызывающему процессу
нужны права на чтение.

GETPID Системный вызов возвращает значение sempid
семафору semnum-th (например, идентификатор
процесса, который последним делал вызов semop
семафору semnum-th). Для этого вызывающему
процессу нужны права на чтение.

GETVAL системный вызов возвращает значение semval
семафору semnum-th. Для этого вызывающему
процессу нужны права на чтение.

GETZCNT Системный вызов возвращает значение semzcnt
семафору semnum-th (например, количество
процессов, ожидающих, чтобы значение semval
семафора semnum-th стало равным нулю). Для
этого вызывающему процессу нужны права на
чтение.

SETALL Установить значение semval всех семафоров
равным значениям элементов массива, на который
указывает arg.array, изменяя также sem_ctime,
являющееся членом структуры semid_ds ; а эта
структура ассоциируется с набором семафоров.
История отменяемых операций удаляется для всех
измененных семафоров во всех процессах.
Процессы, находящиеся в очереди,
активизируются, если semval становится равным
нулю или значение его увеличивается. Аргумент
semnum игнорируется. Для этого вызывающему
процессу нужны права на чтение.

SETVAL Установите значение semval на указанное в
arg.val для всех семафоров semnum-th, изменяя
также sem_ctime в структуре semid_ds,
соотносимой с набором семафоров. История
отмененных операций удаляется для всех
измененных семафоров во всех процессах.
Процессы, находящиеся в очереди,
активизируются, если semval становится равным
нулю или значение его увеличивается.
Вызывающему процессу потребуется право на его
изменение.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При ошибке semctl вернет -1, а переменной errno
присваивается номер ошибки. Иначе говоря, системный вызов
возвращает положительное значение, зависящее от cmd:

GETNCNT значение семафора равно semncnt.

GETPID значение семафора равно sempid.

GETVAL значение семафора равно semval.

GETZCNT значение семафора равно semzcnt.

КОДЫ ОШИБОК
В случае ошибки errno будет присвоено одно из следующих
значений:

EACCES Вызывающий процесс не имеет права доступа,
необходимого для запуска cmd.

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

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

EINVAL Неверное значение cmd или semid.

EPERM Аргумент cmd имеет значение IPC_SET или
IPC_RMID, но вызывающий процесс не имеет
достаточных привилегий на выполнение команды.

ERANGE Аргумент cmd имеет значение SETALL или SETVAL,
или значение, присваиваемое semval (для
некоторых семафоров в наборе), меньше нуля или
больше, чем стандартное значение SEMVMX.

ЗАМЕЧАНИЯ
Управляющие вызовы IPC_INFO, SEM_STAT и SEM_INFO
используются программой ipcs(8). В будущем это может быть
изменено, как требуется, или перенесено в файловую систему
proc.

Многие поля в структуре struct msqid_ds Linux 2.2 были
короткими, в версии 2.4 они стали длиннее. Для
эффективного применения этого необходима перекомпиляция
версии в glibc-2.1.91 или более позднюю версию. (Ядро
различает старые и новые вызовы по флагу IPC_64 в
аргументе cmd.)

На работу наборов семафоров и функции semctl влияет лимит

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

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

В Linux фунцкия semctl не является системным вызовом, но
реализована через системный вызов ipc(2).

СООТВЕТСТВИЕ СТАНДАРТАМ
SVr4, SVID. SVr4 описывает дополнительные коды ошибок
EINVAL и EOVERFLOW.