draft/man2/semop.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified 1996-10-22, Eric S. Raymond <esr@thyrsus.com>
  26 .\" Modified 2002-01-08, Michael Kerrisk <mtk.manpages@gmail.com>
  27 .\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com>
  28 .\" Modified 2004-05-27, Michael Kerrisk <mtk.manpages@gmail.com>
  29 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  30 .\"     Language and formatting clean-ups
  31 .\"     Added notes on /proc files
  32 .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop()
  33 .\" 2007-07-09, mtk, Added an EXAMPLE code segment.
  34 .\"
  35 .\"*******************************************************************
  36 .\"
  37 .\" This file was generated with po4a. Translate the source file.
  38 .\"
  39 .\"*******************************************************************
  40 .\"
  41 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  42 .\"         all rights reserved.
  43 .\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  44 .\" Updated 2003-02-09, Kentaro Shirakata <argrath@ub32.org>
  45 .\" Updated 2003-09-12, Kentaro Shirakata <argrath@ub32.org>
  46 .\" Updated 2005-03-01, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  47 .\" Updated 2005-04-17, Akihiro MOTOKI
  48 .\" Updated 2005-09-06, Akihiro MOTOKI
  49 .\" Updated 2007-05-01, Akihiro MOTOKI, LDP v2.46
  50 .\" Updated 2012-05-29, Akihiro MOTOKI <amotoki@gmail.com>
  51 .\" Updated 2013-05-06, Akihiro MOTOKI <amotoki@gmail.com>
  52 .\"
  53 .TH SEMOP 2 2014\-12\-31 Linux "Linux Programmer's Manual"
  54 .SH 名前
  55 semop, semtimedop \- System V セマフォの操作
  56 .SH 書式
  57 .nf
  58 \fB#include <sys/types.h>\fP
  59 \fB#include <sys/ipc.h>\fP
  60 \fB#include <sys/sem.h>\fP
  61 .sp
  62 \fBint semop(int \fP\fIsemid\fP\fB, struct sembuf *\fP\fIsops\fP\fB, size_t \fP\fInsops\fP\fB);\fP
  63 .sp
  64 \fBint semtimedop(int \fP\fIsemid\fP\fB, struct sembuf *\fP\fIsops\fP\fB, size_t \fP\fInsops\fP\fB,\fP
  65 \fB               const struct timespec *\fP\fItimeout\fP\fB);\fP
  66 .fi
  67 .sp
  68 .in -4n
  69 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  70 .in
  71 .sp
  72 \fBsemtimedop\fP(): _GNU_SOURCE
  73 .SH 説明
  74 System\ V セマフォ集合 (semaphore set) のメンバーの各セマフォは 以下の関連情報を持っている:
  75 .sp
  76 .in +4n
  77 .nf
  78 unsigned short  semval;   /* セマフォ値 */
  79 unsigned short  semzcnt;  /* ゼロを待つプロセス数 */
  80 unsigned short  semncnt;  /* 増加を待つプロセス数 */
  81 pid_t           sempid;   /* 最後に操作を行なったプロセスの ID */
  82 .sp
  83 .in -4n
  84 .fi
  85 \fBsemop\fP()  は \fIsemid\fP で指定されたセマフォ集合の選択されたセマフォに対して操作を行う。 \fIsops\fP は \fInsops\fP
  86 個の要素の配列を指し、配列の各要素は個々のセマフォに対する操作を示す構造体である。その型は \fIstruct sembuf\fP で、次のメンバを持つ:
  87 .sp
  88 .in +4n
  89 .nf
  90 unsigned short sem_num;  /* セマフォ番号 */
  91 short          sem_op;   /* セマフォ操作 */
  92 short          sem_flg;  /* 操作フラグ */
  93 .sp
  94 .in -4n
  95 .fi
  96 \fIsem_flg\fP には \fBIPC_NOWAIT\fP と \fBSEM_UNDO\fP が設定できる。 \fBSEM_UNDO\fP
  97 が指定された操作は、そのプロセスが終了した時に自動的に取り消される。
  98 .PP
  99 \fIsops\fP に含まれる操作の集合は、 \fI配列の順序\fP で、 \fIアトミックに\fP 実行される。
 100 すなわち、全ての操作が完全に実行されるか、全く実行されないかの どちらかとなる。 全ての操作が直ちに実行できない場合のこのシステムコールの振る舞いは
 101 個々の操作の \fIsem_flg\fP フィールドに \fBIPC_NOWAIT\fP が存在するかによって決まり、後述のようになる。
 102
 103 それぞれの操作はセマフォ集合の \fIsem_num\fP番目 のセマフォに対して実行される。セマフォ集合の最初のセマフォには 番号 0 が振られる。
 104 そして操作は三種類あり、 \fIsem_op\fP の値で区別される。
 105 .PP
 106 \fIsem_op\fP が正の整数の場合、その値をセマフォの値 (\fIsemval\fP) に加算する。 さらに、この操作で \fBSEM_UNDO\fP
 107 が指定されていた場合は、 システムはこのセマフォのの調整値 (\fIsemadj\fP) から値 \fIsem_op\fP を減算する。 この操作は必ず実行でき、
 108 スレッドの停止は起こらない。 呼び出し元プロセスは対象のセマフォ集合を変更する許可がなければならない。
 109 .PP
 110 \fIsem_op\fP が 0 の場合、「ゼロまで待つ」操作である。この場合、プロセスは そのセマフォ集合に対する読み込み許可がなければならない。
 111 \fIsemval\fP が 0 ならば、操作は直ちに行われる。 \fIsemval\fP が 0 でない場合、 \fIsem_flg\fP に
 112 \fBIPC_NOWAIT\fP が指定されていれば、 \fBsemop\fP()  は失敗し、 \fBerrno\fP に \fBEAGAIN\fP が設定される (このとき
 113 \fIsops\fP に対する操作は全く実行されない)。 \fIsem_flg\fP に \fBIPC_NOWAIT\fP が指定されていない場合、 \fIsemzcnt\fP
 114 (セマフォ値が 0 になるのを待っているスレッドの数) を 1 増加させて、 以下のいずれかが起こるまでスレッドを停止 (sleep) する。
 115 .IP \(bu 3
 116 \fIsemval\fP が 0 になった: このとき \fIsemzcnt\fP の値は 1 減算される。
 117 .IP \(bu
 118 セマフォ集合が削除された: このとき \fBsemop\fP()  は失敗し、 \fIerrno\fP に \fBEIDRM\fP が設定される。
 119 .IP \(bu
 120 呼び出し元スレッドがシグナルを捕獲した: このとき \fIsemzcnt\fP の値は 1 減算され、 \fBsemop\fP()  は失敗し \fIerrno\fP に
 121 \fBEINTR\fP が設定される。
 122 .PP
 123 \fIsem_op\fP が 0 未満の場合、プロセスにはそのセマフォ集合を変更する許可がなければ ならない。 \fIsemval\fP が \fIsem_op\fP
 124 の絶対値以上の場合は、操作は直ちに実行される: \fIsemval\fP から \fIsem_op\fP の絶対値を減算し、さらに、この操作に
 125 \fBSEM_UNDO\fP が指定されている場合は、このセマフォの調整値 (\fIsemadj\fP) に \fIsem_op\fP の絶対値を加算する。
 126 \fIsemval\fP が \fIsem_op\fP の絶対値より小さく、 \fIsem_flg\fP に \fBIPC_NOWAIT\fP が指定された場合は、
 127 \fBsemop\fP()  は失敗し、 \fIerrno\fP に \fBEAGAIN\fP が設定される (このとき \fIsops\fP の操作は全く実行されない)。
 128 \fIsemval\fP が \fIsem_op\fP の絶対値より小さく、 \fBIPC_WAIT\fP が指定されていない場合は、 \fIsemncnt\fP
 129 (このセマフォの値が増加するのを待っているスレッド数のカウンター)  を 1 増加させて、以下のいずれかが起こるまでスレッドを停止 (sleep)
 130 する。
 131 .IP \(bu 3
 132 \fIsemval\fP が \fIsem_op\fP の絶対値以上になった。この時点で、操作は上述の通り実行される。
 133 .IP \(bu
 134 セマフォ集合がシステムから削除された: このとき \fBsemop\fP()  は失敗し \fIerrno\fP に \fBEIDRM\fP が設定される。
 135 .IP \(bu
 136 呼び出したスレッドがシグナルを捕獲した: このとき \fIsemncnt\fP が 1 減算され、 \fBsemop\fP()  は失敗し \fIerrno\fP に
 137 \fBEINTR\fP が設定される。
 138 .PP
 139 .\" and
 140 .\" .I sem_ctime
 141 操作が成功した場合、 \fIsops\fP が指す配列によって操作対象となった各セマフォの \fIsempid\fP メンバーには呼び出し元のプロセス ID
 142 が設定される。さらに \fIsem_otime\fP に現在時刻が設定される。
 143 .SS semtimedop()
 144 \fBsemtimedop\fP() 関数の振る舞いは \fBsemop\fP() と全く同じだが、呼び出し元
 145 スレッドが停止する場合、停止期間の上限が \fItimeout\fP 引き数の指す
 146 \fItimespec\fP 構造体で指定された時間となる点だけが異なる (この停止期間は
 147 システムクロックの粒度に切り上げられ、カーネルのスケジューリング遅延に
 148 より、この停止期間は少しだけ長くなる可能性がある)。
 149 指定した制限時間に達した場合は、 \fBsemtimedop\fP() は失敗し、 \fIerrno\fP に
 150 \fBEAGAIN\fP が設定される (このとき \fIsops\fP の操作は実行されない)。
 151 \fItimeout\fP 引き数が NULL の場合、 \fBsemtimedop\fP() 関数の振る舞いは
 152 \fBsemop\fP() 関数と全く同じになる。
 153
 154 \fBsemtimeop\fP() がシグナルにより割り込まれた場合、呼び出しはエラー \fBEINTR\fP で失敗し、 \fItimeout\fP
 155 の内容は変更されないままとなる点に注意すること。
 156 .SH 返り値
 157 成功した場合、 \fBsemop\fP()  と \fBsemtimedop\fP()  は 0 を返す。そうでなければ \-1 を返し、 エラーを示す
 158 \fIerrno\fP を設定する。
 159 .SH エラー
 160 失敗した場合、 \fIerrno\fP に以下のどれかが設定される:
 161 .TP
 162 \fBE2BIG\fP
 163 \fInsops\fP 引き数が \fBSEMOPM\fP より大きい。 \fBSEMOPM\fP は一回のシステムコールで許される操作の最大個数である。
 164 .TP
 165 \fBEACCES\fP
 166 呼び出し元プロセスには指定されたセマフォ操作を行うのに 必要なアクセス許可がなく、 \fBCAP_IPC_OWNER\fP ケーパビリティもない。
 167 .TP
 168 \fBEAGAIN\fP
 169 操作を直ちに処理することができず、かつ \fIsem_flg\fP に \fBIPC_NOWAIT\fP が指定されているか \fItimeout\fP
 170 で指定された制限時間が経過した。
 171 .TP
 172 \fBEFAULT\fP
 173 引き数 \fIsops\fP か \fItimeout\fP が指しているアドレスにアクセスできない。
 174 .TP
 175 \fBEFBIG\fP
 176 ある操作で、 \fIsem_num\fP の値が 0 未満か、集合内のセマフォの数以上である。
 177 .TP
 178 \fBEIDRM\fP
 179 セマフォ集合が削除された。
 180 .TP
 181 \fBEINTR\fP
 182 このシステムコールで停止している時にスレッドがシグナルを捕獲した。 \fBsingle\fP(7) 参照。
 183 .TP
 184 \fBEINVAL\fP
 185 セマフォ集合が存在しないか、 \fIsemid\fP が 0 未満であるか、 \fInsops\fP が正の数でない。
 186 .TP
 187 \fBENOMEM\fP
 188 ある操作で \fIsem_flg\fP に \fBSEM_UNDO\fP が指定されたが、システムにアンドゥ構造体に割り当てる十分なメモリーがない。
 189 .TP
 190 \fBERANGE\fP
 191 ある操作で \fIsem_op+semval\fP が \fBSEMVMX\fP より大きい。 \fBSEMVMX\fP は \fIsemval\fP
 192 の最大値で、その値は実装依存である。
 193 .SH バージョン
 194 \fBsemtimedop\fP()  は Linux 2.5.52 で初めて登場し、 それからカーネル 2.4.22 にも移植された。
 195 \fBsemtimedop\fP()  の glibc でのサポートはバージョン 2.3.3 で初めて登場した。
 196 .SH 準拠
 197 .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC.
 198 SVr4, POSIX.1\-2001.
 199 .SH 注意
 200 .\" Like Linux, the FreeBSD man pages still document
 201 .\" the inclusion of these header files.
 202 Linux や POSIX の全てのバージョンでは、 \fI<sys/types.h>\fP と \fI<sys/ipc.h>\fP
 203 のインクルードは必要ない。しかしながら、いくつかの古い実装ではこれらのヘッダーファイルのインクルードが必要であり、 SVID
 204 でもこれらのインクルードをするように記載されている。このような古いシステムへの移植性を意図したアプリケーションではこれらのファイルをインクルードする必要があるかもしれない。
 205
 206 あるプロセスの \fIsem_undo\fP 構造体は \fBfork\fP(2)  で生成された子プロセスには継承されないが、 \fBexecve\fP(2)
 207 システムコールの場合は継承される。
 208 .PP
 209 \fBsemop\fP()  はシグナルハンドラーによって中断された後に、 決して自動的に再開することはない。 たとえシグナルハンドラーの設定時に
 210 \fBSA_RESTART\fP フラグがセットされていても再開することはない
 211
 212 セマフォの調整値 (\fIsemadj\fP) は、プロセス毎のセマフォ毎の整数で、 \fBSEM_UNDO\fP
 213 フラグを指定して行われた、セマフォに対するすべての操作の合計値を反転したものである。 各プロセスは \fIsemadj\fP の値のリストを保持する \(em
 214 リストのそれぞれの値は \fBSEM_UNDO\fP を使って操作が行われた個々のセマフォに対応する。 プロセスが終了する際、 セマフォ毎の
 215 \fIsemadj\fP の各々の値が対応するセマフォに加算される。 これにより、そのプロセスがそのセマフォに対して行った操作の影響が取り消される
 216 (ただし、下記の「バグ」を参照)。 \fBsemctl\fP(2) の \fBSETVAL\fP や \fBSETALL\fP を使ってセマフォの値が直接設定された場合、
 217 すべてのプロセスの対応する \fIsemadj\fP の値がクリアされる。 \fBclone\fP(2) の \fBCLONE_SYSVSEM\fP フラグを使うと、
 218 複数のプロセスがひとつの \fIsemadj\fP リストを共有できる。 詳細は \fBclone\fP(2) を参照。
 219
 220 あるセマフォの \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, \fIsemnct\fP の値はいずれも、適切な操作を指定して
 221 \fBsemctl\fP(2)  を呼び出すことで取得できる。
 222 .SS セマフォの上限
 223 セマフォ集合のリソースに関する制限のうち、 \fBsemop\fP()  に影響を及ぼすものを以下に挙げる:
 224 .TP
 225 \fBSEMOPM\fP
 226 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 227 一回の \fBsemop\fP()  で許される操作の最大数 (32)。 (Linux では、この制限値は \fI/proc/sys/kernel/sem\fP
 228 の第3フィールドに対応し、読み出しも変更もできる)。
 229 .TP
 230 \fBSEMVMX\fP
 231 \fIsemval\fP が取り得る最大値: 実装依存 (32767)。
 232 .PP
 233 以下の値に関しては実装依存の制限はない。 終了時の調整 (adjust on exit) の最大値 (\fBSEMAEM\fP)、
 234 システム全体のアンドゥ構造体の最大数 (\fBSEMMNU\fP)、 プロセスあたりのアンドゥ構造体の最大数。
 235 .SH バグ
 236 プロセスが終了する際、プロセスに対応する \fIsemadj\fP の集合を使って、 \fBSEM_UNDO\fP
 237 フラグ付きで実行された全てのセマフォ操作の影響を取り消す。 これによりある問題が発生する: これらのセマフォの調整を行っていると、 中にはセマフォの値が
 238 0 未満の値にしようとする場合が出てくる。 このような場合、どのように実装するべきか? ひとつの考えられる手法は、全てのセマフォ調整が実行されるまで
 239 停止することである。しかし、この方法ではプロセスの終了が 長時間にわたって停止されることがあるので望ましくない。
 240 しかもどれくらい長時間になるかは分からない。 別の選択肢として、このようなセマフォ調整を完全に無視してしまう方法がある (これはセマフォ操作として
 241 \fBIPC_NOWAIT\fP が指定するのと少し似ている)。 Linux は第三の手法を採用している: セマフォの値を出来るだけ (つまり 0 まで)
 242 減少させて、プロセスの終了を直ちに続行できるようにしている。
 243
 244 .\" The bug report:
 245 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2
 246 .\" the fix:
 247 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2
 248 カーネル 2.6.x (x <= 10) には、ある状況においてセマフォ値が 0 になるのを 待っているスレッドが、セマフォ値が実際に 0
 249 になったときに起床 (wake up)  されない、というバグがある。このバグはカーネル 2.6.11 で修正されている。
 250 .SH 例
 251 以下の部分的なコードは、 セマフォ 0 の値が 0 になるのを待ってから、 セマフォの値を 1 加算する処理を、 \fBsemop\fP()
 252 を使ってアトミック (atomically) に行う。
 253 .nf
 254
 255     struct sembuf sops[2];
 256     int semid;
 257
 258     /* Code to set \fIsemid\fP omitted */
 259
 260     sops[0].sem_num = 0;        /* Operate on semaphore 0 */
 261     sops[0].sem_op = 0;         /* Wait for value to equal 0 */
 262     sops[0].sem_flg = 0;
 263
 264     sops[1].sem_num = 0;        /* Operate on semaphore 0 */
 265     sops[1].sem_op = 1;         /* Increment value by one */
 266     sops[1].sem_flg = 0;
 267
 268     if (semop(semid, sops, 2) == \-1) {
 269         perror("semop");
 270         exit(EXIT_FAILURE);
 271     }
 272 .fi
 273 .SH 関連項目
 274 \fBclone\fP(2), \fBsemctl\fP(2), \fBsemget\fP(2), \fBsigaction\fP(2),
 275 \fBcapabilities\fP(7), \fBsem_overview\fP(7), \fBsvipc\fP(7), \fBtime\fP(7)
 276 .SH この文書について
 277 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 278 である。プロジェクトの説明とバグ報告に関する情報は
 279 http://www.kernel.org/doc/man\-pages/ に書かれている。