semctl() - セマフォー制御操作

標準

標準/拡張機能	C/C++	依存項目
XPG4 XPG4.2 Single UNIX Specification、バージョン 3	両方

形式

#define _XOPEN_SOURCE
#include <sys/sem.h>

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

機能説明

semctl() 関数は、引数 cmd によって指定されているとおりに、セマフォー・セット semid の制御操作を実行します。

引数 cmd の値に従って、引数 semnum は無視されるか、あるいは 1 つの特定セマフォー番号を識別します。

4 番目の引数はオプションで、要求された操作によって異なります。要求された場合には、これは次のような union semun 型で、アプリケーション・プログラムで明示的に宣言する必要があります。

union semun {
     int              val;
     struct semid_ds *buf;
     unsigned short  *array;
} arg;

セマフォー・セットの各セマフォーは、次の無名データ構造によって表されます。

unsigned short int

semval

セマフォー値

pid_t

sempid

最終操作のプロセス ID

unsigned sort int

semcnt

semval が現行値より大きくなるのを待っているプロセスの数

unsigned short int

semzcnt

semval がゼロになるのを待っているプロセスの数

semctl() を使用して、コマンド GETVAL、SETVAL、GETPID、GETNCNT、および GETZCNT の 1 つの特定セマフォー番号を識別する場合、この無名データ構造に対し、セマフォー semnum についての参照が行われます。

引数 cmd で指定される、以下のようなセマフォー制御操作が指定される場合があります。各操作に必要な許可のレベルは、コマンドと共に示されます。以下のシンボリック定数は、<sys/sem.h> ヘッダーにより定義されます。

GETVAL

現行プロセスに読み取り許可がある場合には、semval の値を戻します。

SETVAL

semval の値を arg.val に設定します。この場合 arg は、semctl() の 4 番目の引数です。このコマンドが正常に実行されると、すべてのプロセスで指定されているセマフォーに対応する semadj 値がクリアされます。このコマンドには、変更許可が必要です。__IPC_BINSEM セマフォー・セットの場合、設定できる値は 0 と 1 だけです。

GETPID

現行プロセスに読み取り許可がある場合には、最新のプロセスを戻して、セマフォー (sempid) を更新します。

GETNCNT

現行プロセスに読み取り許可がある場合には、セマフォーが現行値より大きくなるのを待機中のスレッド数が戻されます。

GETZCNT

現行プロセスに読み取り許可がある場合には、セマフォーがゼロになるのを待機中のスレッド数が戻されます。__IPC_BINSEM セマフォー・セットの場合、この操作により常にゼロが戻されます。つまり、このセマフォー・セットのタイプでセマフォーがゼロになるまでスレッドは待機できません。

GETALL

セマフォー・セット内の各セマフォーごとに semvals を保管し、arg.array で示されている配列に入れます。この場合、arg は semctl() の 4 番目の引数です。GETALL には読み取り許可が必要です。割り振られたストレージがセマフォー・エレメント数を保持するのに十分な大きさであることの保証は、呼び出し元が行います。保管済みセマフォー値数は、sem_nsems で、IPC_STAT コマンドを使用して取得できます。

SETALL

セマフォー・セット内の各セマフォーごとに、arg.array によって示されている配列に応じて semval を設定します。この場合、arg は、semctl() の 4 番目の引数です。SETALL には変更許可が必要です。それぞれの semval 値は、ゼロまたは正であることが必要です。このコマンドが正常に実行されると、すべてのプロセスで指定された各セマフォーに対応する semadj 値がクリアされます。割り振られたストレージがセマフォー・エレメント数を保持するのに十分な大きさであることの保証は、呼び出し元が行います。設定されているセマフォー値の数は、sem_nsems です。この値は、IPC_STAT コマンドを使用して取得することができます。 semget で __IPC_BINSEM を指定した場合、他のスレッドがこのセマフォーについてセマフォー操作を実行する可能性がある間は、セマフォー値を更新する際にシリアライズが行われないことがあるので、このオプションは使用しないでください。このため、__IPC_BINSEM セマフォー・セットに対して semop がとられた後は、SETALL を実行することはできません。また、__IPC_BINSEM セマフォー・セットの場合、設定できる値は 0 と 1 だけです。

IPC_STAT

このコマンドは、semid によって指定されたセマフォー ID の状況情報を取得します。これには、読み取り許可が必要です。この情報は、データ構造 semid_ds によって定義された 4 番目の引数によって指定されるアドレスに保管されます。

IPC_SET

sem_perm.uid、sem_perm.gid、および sem_perm.mode の値を、semid によって指定されたセマフォー ID 用の semid_ds データ構造に設定します。これらの値は、4 番目の引数によって指された semid_ds に検出された値に設定されます。

sem_perm.uid および semperm.gid にはどのような値も設定できます。

semget() 関数の引数 semflg のもとで定義されるモード・ビットだけを sem_perm.mode に設定することができます。

このコマンドを実行できるのは、該当する特権のあるプロセス、あるいは semid と関連した semid_ds 構造体内の sem_perm.cuid または sem_perm.uid の値のいずれかと等しい有効なユーザー ID を持つプロセスだけです。

IPC_RMID

引数 semid で指定されたセマフォー ID を、システムから除去し、semid_ds 構造体内のセマフォーのセット用のストレージを解放します。

このコマンドを実行できるのは、該当する特権のあるプロセス、あるいは semid と関連した semid_ds 構造体内の sem_perm.cuid または sem_perm.uid の値のいずれかと等しい有効なユーザー ID を持つプロセスだけです。__IPC_BINSEM セマフォー・セットの場合、使用するすべての semop は、セマフォー ID を削除する前に完了させることをお勧めします。

戻り値

正常に実行された場合、semctl() によって戻される値は、以下のように引数 cmd の値により異なります。

GETVAL: semval 値が戻されます
GETPID: sempid 値が戻されます
GETNCNT: semncnt 値が戻されます
GETZCNT: semzcnt 値が戻されます
その他すべて: ゼロ値が戻される

正常に実行されなかった場合、semctl() は -1 を戻して、errno を次のいずれかの値に設定します。

エラー・コード: 説明
EACCES: 呼び出しプロセスに対する操作許可 (読み取りまたは書き込み) は拒否されます。
EINVAL: 引数 semid の値が、無効セマフォー ID であるか、または semnum の値が、ゼロより小さいか、セット中のセマフォー数より大きいか等しいか、または、引数 cmd が、無効コマンドか、あるいは sem_perm.mode に指定されたビットが、未定義です。semnum の有効範囲は、0 ～セット中のセマフォー数から 1 を引いた値です。
EPERM: 引数 cmd は IPC_RMID または IPC_SET の値を持ち、呼び出し元の有効ユーザー ID は、該当する特権のプロセスおよび semid と関連した semid_ds データ構造の sem_perm.cuid または sem_perm.uid の値の有効ユーザー ID ではありません。
ERANGE: 引数 cmd は SETVAL または SETALL の値をとり、設定される semval 値は <sys/sem.h> で定義されているシステム制限を超えています。

semctl() - セマフォー制御操作

標準

形式

機能説明

戻り値

関連情報