Man page - semctl(2)

Packages contains this manual

Available languages:

en fr pl ja

Manual

SEMCTL

名 前
書 式
説 明
返 り 値
エ ラ ー
準 拠
注 意
The sempid value
例
関 連 項 目
こ の 文 書 に つ い て

名 前

semctl - System V セ マ フ ォ の 制 御 操 作 を 行 な う

書 式

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>

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

説 明

semctl () は 、 semid で 指 定 さ れ た System V セ マ フ ォ 集 合 (semaphore set) ま た は セ マ フ ォ 集 合 の semnun 番 目 の セ マ フ ォ に 対 し て 、 cmd で 指 定 さ れ た 制 御 操 作 を 行 な う (集 合 内 の セ マ フ ォ の 番 号 は 0 か ら 始 ま る )。

こ の 関 数 は 、 cmd の 値 に 依 存 し て 、 3 個 ま た は 4 個 の 引 数 を 持 つ 。 引 数 が 4 個 の 場 合 、 第 4 引 数 の 型 は union semun で あ る 。 呼 び 出 し 元 プ ロ グ ラ ム は 、 こ の 共 用 体 (union) を 以 下 の よ う に 定 義 し な け れ ば な ら な い 。

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; /* 所 有 権 と 許 可 */
time_t sem_otime; /* 最 後 の semop の 時 刻 */
time_t sem_ctime; /* 作 成 時 刻 /semctl() に よ り
最 後 に 変 更 が 行 わ れ た 時 刻 */
unsigned long sem_nsems; /* 集 合 内 の セ マ フ ォ の 数 */
};

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

Time of last semop (2) system call.

sem_ctime

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

sem_nsems

Number of semaphores in the set. Each semaphore of the set is referenced by a nonnegative integer ranging from 0 to sem_nsems-1 .

ipc_perm 構 造 体 は 以 下 の よ う に 定 義 さ れ て い る (強 調 さ れ た フ ィ ー ル ド は IPC_SET を 使 っ て 設 定 可 能 で あ る ):

struct ipc_perm {
key_t __key; /* semget(2) に 与 え ら れ る キ ー */
uid_t uid ; /* 所 有 者 (owner) の 実 効 UID */
gid_t gid ; /* 所 有 者 の 実 効 GID */
uid_t cuid; /* 作 成 者 (creator) の 実 効 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:

Image grohtml-5999-1.png

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 に 関 連 づ け ら れ た カ ー ネ ル デ ー タ 構 造 体 の 情 報 を arg.buf で 指 さ れ た semid_ds 構 造 体 へ コ ピ ー す る 。 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 が 設 定 さ れ る )。 呼 び 出 し た プ ロ セ ス の 実 効 ユ ー ザ ー ID が そ の セ マ フ ォ 集 合 の 作 成 者 ま た は 所 有 者 と 一 致 す る か 、 呼 び 出 し た 人 が 特 権 を 持 た な け れ ば な ら な い 。 semnum 引 数 は 無 視 さ れ る 。

IPC_INFO (Linux 固 有 )

シ ス テ ム 全 体 で の セ マ フ ォ の 制 限 と パ ラ メ ー タ ー に 関 す る 情 報 を 、 arg.__buf が 指 す 構 造 体 に 入 れ て 返 す 。 こ の 構 造 体 は seminfo 型 で あ る 。 seminfo は _GNU_SOURCE 機 能 検 査 マ ク ロ が 定 義 さ れ た 場 合 に <sys/sem.h> で 以 下 の よ う に 定 義 さ れ る :

struct seminfo {
int semmap; /* セ マ フ ォ マ ッ プ の 最 大 エ ン ト リ ー 数 ;
カ ー ネ ル 内 で は 未 使 用 */
int semmni; /* セ マ フ ォ 集 合 の 最 大 数 */
int semmns; /* 全 セ マ フ ォ 集 合 中 の セ マ フ ォ の
最 大 数 */
int semmnu; /* ア ン ド ゥ 構 造 体 の シ ス テ ム 全 体 で の
最 大 数 ; カ ー ネ ル 内 で は 未 使 用 */
int semmsl; /* 一 つ の セ マ フ ォ 集 合 の 最 大 セ マ フ ォ 数 */
int semopm; /* semop(2) に 渡 す 操 作 の 最 大 数 */
int semume; /* プ ロ セ ス あ た り の ア ン ド ゥ エ ン ト リ ー
の 最 大 数 ; カ ー ネ ル 内 で は 未 使 用 */
int semusz; /* 構 造 体 sem_undo の サ イ ズ */
int semvmx; /* セ マ フ ォ の 最 大 値 */
int semaem; /* セ マ フ ォ の 調 整 (semaphore adjustment;
SEM_UNDO) の た め に 記 録 さ れ る 最 大 値 */
};

設 定 semmsl , semmns , semopm , semmni は /proc/sys/kernel/sem 経 由 で 変 更 可 能 で あ る 。 詳 し く は proc (5) を 参 照 。

SEM_INFO (Linux 固 有 )

IPC_INFO の と き と 同 じ 情 報 を 格 納 し た seminfo 構 造 体 を 返 す 。 但 し 、 以 下 の フ ィ ー ル ド に は セ マ フ ォ が 消 費 し て い る シ ス テ ム 資 源 に 関 す る 情 報 が 格 納 さ れ る 点 が 異 な る 。 semusz フ ィ ー ル ド は 現 在 シ ス テ ム 上 に 存 在 す る セ マ フ ォ 集 合 の 数 を 返 す 。 semaem フ ィ ー ル ド は シ ス テ ム 上 の 全 て の セ マ フ ォ 集 合 に 含 ま れ る セ マ フ ォ の 総 数 を 返 す 。

SEM_STAT (Linux 固 有 )

IPC_STAT と 同 じ く semid_ds 構 造 体 を 返 す 。 但 し 、 semid 引 数 は 、 セ マ フ ォ 識 別 子 で は な く 、 シ ス テ ム 上 の 全 て の セ マ フ ォ 集 合 に 関 す る 情 報 を 管 理 す る カ ー ネ ル の 内 部 配 列 へ の イ ン デ ッ ク ス で あ る 。

SEM_STAT_ANY (Linux 固 有 , Linux 4.17 以 降 )

Return a seminfo structure containing the same information as for SEM_STAT . However, sem_perm.mode is not checked for read access for semid meaning that any user can employ this operation (just as any user may read /proc/sysvipc/sem to obtain the same information).

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

集 合 の semnum 番 目 の セ マ フ ォ の sempid の 値 を 返 す 。 こ の 値 は 、 そ の セ マ フ ォ に 対 し て 最 後 に 操 作 を 行 っ た プ ロ セ ス の PID で あ る (た だ し 「 バ グ 」 を 参 照 )。 呼 び 出 し た プ ロ セ ス は そ の セ マ フ ォ 集 合 に 読 み 込 み 許 可 を 持 た な け れ ば な ら な い 。

GETVAL

集 合 の semnum 番 目 の セ マ フ ォ の semval (セ マ フ ォ の 値 ) を 返 す 。 呼 び 出 し た プ ロ セ ス は そ の セ マ フ ォ 集 合 に 読 み 込 み 許 可 を 持 た な け れ ば な ら な い 。

GETZCNT

集 合 の semnum 番 目 の セ マ フ ォ の semzcnt の 値 (つ ま り 、 そ の セ マ フ ォ の 値 が 0 に な る の を 待 っ て い る プ ロ セ ス の 数 ) を 返 す 。 呼 び 出 し た プ ロ セ ス は そ の セ マ フ ォ 集 合 に 読 み 込 み 許 可 を 持 た な け れ ば な ら な い 。

SETALL

集 合 の 全 て の セ マ フ ォ の semval 値 に arg.array で 指 定 さ れ た 値 を 設 定 す る 。 そ の 集 合 に 関 連 す る semid_ds 構 造 体 の sem_ctime メ ン バ ー の 値 も 更 新 す る 。 全 て の プ ロ セ ス の セ マ フ ォ の 変 更 に つ い て の ア ン ド ゥ エ ン ト リ ー ( semop (2) を 参 照 ) は 消 去 (clear) さ れ る 。 セ マ フ ォ の 値 の 変 更 に よ り 、 他 の プ ロ セ ス 内 で ブ ロ ッ ク さ れ て い る semop (2) コ ー ル の 続 行 が 許 可 さ れ る と 、 そ れ ら の プ ロ セ ス は 起 こ さ れ る (wake up)。 semnum 引 数 は 無 視 さ れ る 。 呼 び 出 し た プ ロ セ ス は そ の セ マ フ ォ 集 合 に 変 更 (書 き 込 み ) 許 可 を 持 た な け れ ば な ら な い 。

SETVAL

集 合 の semnum 番 目 の セ マ フ ォ の セ マ フ ォ 地 ( semval ) に arg.val の 値 を 設 定 す る 。 そ の 集 合 に 関 連 す る semid_ds 構 造 体 の sem_ctime メ ン バ ー の 値 も 更 新 す る 。 全 て の プ ロ セ ス の セ マ フ ォ の 変 更 に つ い て の ア ン ド ゥ エ ン ト リ ー は 消 去 さ れ る 。 セ マ フ ォ の 値 の 変 更 に よ り 、 他 の プ ロ セ ス 内 で ブ ロ ッ ク さ れ て い る semop (2) コ ー ル の 続 行 が 許 可 さ れ る と 、 そ れ ら の プ ロ セ ス は 起 こ さ れ る (wake up)。 呼 び 出 し た プ ロ セ ス は そ の セ マ フ ォ 集 合 に 変 更 (書 き 込 み ) 許 可 を 持 た な け れ ば な ら な い 。

返 り 値

失 敗 し た 場 合 、 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

The argument cmd has one of the values GETALL , GETPID , GETVAL , GETNCNT , GETZCNT , IPC_STAT , SEM_STAT , SEM_STAT_ANY , SETALL , or SETVAL and the calling process does not have the required permissions on the semaphore set and does not have the CAP_IPC_OWNER capability in the user namespace that governs its IPC namespace.

EFAULT

arg.buf ま た は arg.array で 指 さ れ て い る ア ド レ ス に ア ク セ ス す る こ と が で き な い 。

EIDRM

セ マ フ ォ 集 合 が 削 除 さ れ た 。

EINVAL

cmd ま た は semid に 無 効 な 値 が 指 定 さ れ た 。 も し く は 、 SEM_STAT 操 作 の 場 合 に 、 semid で 指 定 さ れ た イ ン デ ッ ク ス 値 が 現 在 未 使 用 の 配 列 の ス ロ ッ ト を 参 照 い て い た 。

EPERM

cmd 引 数 に IPC_SET ま た は IPC_RMID が 指 定 さ れ 、 呼 び 出 し た プ ロ セ ス の 実 効 ユ ー ザ ー ID が セ マ フ ォ の ( sem_perm.cuid で 見 つ か る ) 作 成 者 ま た は ( sem_perm.uid で 見 つ か る ) 所 有 者 で も な く 、 プ ロ セ ス が CAP_SYS_ADMIN ケ ー パ ビ リ テ ィ を 持 た な い 。

ERANGE

cmd 引 数 に SETALL ま た は SETVAL が 指 定 さ れ 、 (集 合 の セ マ フ ォ の ど れ か の ) semval に 設 定 さ れ る 値 が 0 よ り 小 さ い か 、 実 装 の 制 限 SEMVMX よ り も 大 き い 。

準 拠

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

POSIX.1 で は semid_ds 構 造 体 の sem_nsems フ ィ ー ル ド は unsigned short 型 を 持 つ と 規 定 さ れ て お り 、 他 の ほ と ん ど の シ ス テ ム で こ の フ ィ ー ル ド は unsigned short 型 に な っ て い る 。 Linux 2.4 以 前 で は そ う な っ て い た が 、 Linux 2.4 以 降 で は こ の フ ィ ー ル ド は unsigned long 型 で あ る 。

注 意

Linux や POSIX の 全 て の バ ー ジ ョ ン で は 、 <sys/types.h> と <sys/ipc.h> の イ ン ク ル ー ド は 必 要 な い 。 し か し な が ら 、 い く つ か の 古 い 実 装 で は こ れ ら の ヘ ッ ダ ー フ ァ イ ル の イ ン ク ル ー ド が 必 要 で あ り 、 SVID で も こ れ ら の イ ン ク ル ー ド を す る よ う に 記 載 さ れ て い る 。 こ の よ う な 古 い シ ス テ ム へ の 移 植 性 を 意 図 し た ア プ リ ケ ー シ ョ ン で は こ れ ら の フ ァ イ ル を イ ン ク ル ー ド す る 必 要 が あ る か も し れ な い 。

IPC_INFO , SEM_STAT , SEM_INFO 操 作 は ipcs (1) プ ロ グ ラ ム に よ っ て 割 当 ら れ た 資 源 に つ い て 情 報 を 提 供 す る た め に 使 用 さ れ る 。 将 来 的 に は こ れ ら は 変 更 さ れ る か 、 /proc フ ァ イ ル シ ス テ ム イ ン タ ー フ ェ ー ス に 移 動 さ れ る か も し れ な い 。

構 造 体 semid_ds 内 の 多 く の フ ィ ー ル ド は 、 Linux 2.2 で は short 型 だ っ た が 、 Linux 2.4 で は long 型 に な っ た 。 こ の 利 点 を 生 か す に は 、 glibc-2.1.91 以 降 の 環 境 下 で 再 コ ン パ イ ル す れ ば 十 分 で あ る 。 カ ー ネ ル は 新 し い 形 式 の 呼 び 出 し と 古 い 形 式 の 呼 び 出 し を cmd 内 の IPC_64 フ ラ グ で 区 別 す る 。

初 期 の バ ー ジ ョ ン の glibc で は 、 semun 共 用 体 は <sys/sem.h> で 定 義 さ れ て い た が 、 POSIX.1 で は 呼 び 出 し 側 が こ の 共 用 体 を 定 義 す る 必 要 が あ る 。 こ の 共 用 体 が 定 義 さ れ て い な い glibc の バ ー ジ ョ ン で は 、 マ ク ロ _SEM_SEMUN_UNDEFINED が <sys/sem.h> で 定 義 さ れ て い る 。

以 下 は semctl () コ ー ル に 影 響 す る セ マ フ ォ 集 合 の シ ス テ ム 制 限 :

SEMVMX

semval の 最 大 値 : 実 装 依 存 (32767)。

移 植 性 を 高 め る た め の 一 番 良 い 方 法 は 、 常 に 4 個 の 引 数 で semctl () を 呼 び 出 す こ と で あ る 。

The sempid value

POSIX.1 defines sempid as the "process ID of [the] last operation" on a semaphore, and explicitly notes that this value is set by a successful semop (2) call, with the implication that no other interface affects the sempid value.

While some implementations conform to the behavior specified in POSIX.1, others do not. (The fault here probably lies with POSIX.1 inasmuch as it likely failed to capture the full range of existing implementation behaviors.) Various other implementations also update sempid for the other operations that update the value of a semaphore: the SETVAL and SETALL operations, as well as the semaphore adjustments performed on process termination as a consequence of the use of the SEM_UNDO flag (see 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)

こ の 文 書 に つ い て

こ の man ペ ー ジ は Linux man-pages プ ロ ジ ェ ク ト の リ リ ー ス 5.10 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は https://www.kernel.org/doc/man-pages/ に 書 か れ て い る 。