release/man2/semop.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Modified 1996-10-22, Eric S. Raymond <esr@thyrsus.com>
  24 .\" Modified 2002-01-08, Michael Kerrisk <mtk.manpages@gmail.com>
  25 .\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com>
  26 .\" Modified 2004-05-27, Michael Kerrisk <mtk.manpages@gmail.com>
  27 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  28 .\"     Language and formatting clean-ups
  29 .\"     Added notes on /proc files
  30 .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop()
  31 .\" 2007-07-09, mtk, Added an EXAMPLE code segment.
  32 .\"
  33 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  34 .\"         all rights reserved.
  35 .\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  36 .\" Updated 2003-02-09, Kentaro Shirakata <argrath@ub32.org>
  37 .\" Updated 2003-09-12, Kentaro Shirakata <argrath@ub32.org>
  38 .\" Updated 2005-03-01, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  39 .\" Updated 2005-04-17, Akihiro MOTOKI
  40 .\" Updated 2005-09-06, Akihiro MOTOKI
  41 .\" Updated 2007-05-01, Akihiro MOTOKI, LDP v2.46
  42 .\"
  43 .\"WORD:        semaphore               セマフォ
  44 .\"WORD:        member                  メンバー
  45 .\"WORD:        process                 プロセス
  46 .\"WORD:        system call             システムコール
  47 .\"WORD:        undo                    アンドゥ
  48 .\"WORD:        signal                  シグナル
  49 .\"WORD:        catch                   捕獲(catch)
  50 .\"WORD:        process-ID              プロセスID
  51 .\"WORD:        policy                  方針
  52 .\"WORD:        implement               実装
  53 .\"WORD:        queue                   キュー
  54 .\"WORD:        free                    解放(free).
  55 .\"WORD:        memory                  メモリ
  56 .\"WORD:        anonymous structure     無名構造体
  57 .\"WORD:        time limit              制限時間
  58 \"
  59 .TH SEMOP 2 2008-10-04 "Linux" "Linux Programmer's Manual"
  60 .SH 名前
  61 semop, semtimedop \- セマフォの操作
  62 .SH 書式
  63 .nf
  64 .B #include <sys/types.h>
  65 .B #include <sys/ipc.h>
  66 .B #include <sys/sem.h>
  67 .sp
  68 .BI "int semop(int " semid ", struct sembuf *" sops ", unsigned " nsops );
  69 .sp
  70 .BI "int semtimedop(int " semid ", struct sembuf *" sops ", unsigned " nsops ,
  71 .BI "               struct timespec *" timeout );
  72 .fi
  73 .sp
  74 .in -4n
  75 glibc 向けの機能検査マクロの要件
  76 .RB ( feature_test_macros (7)
  77 参照):
  78 .in
  79 .sp
  80 .BR semtimedop ():
  81 _GNU_SOURCE
  82 .SH 説明
  83 セマフォ集合 (semaphore set) のメンバーの各セマフォは
  84 以下の関連情報を持っている:
  85 .sp
  86 .in +4n
  87 .nf
  88 unsigned short  semval;   /* セマフォ値 */
  89 unsigned short  semzcnt;  /* ゼロを待つプロセス数 */
  90 unsigned short  semncnt;  /* 増加を待つプロセス数 */
  91 pid_t           sempid;   /* 最後に操作を行なったプロセス */
  92 .sp
  93 .in -4n
  94 .fi
  95 .BR semop ()
  96 は
  97 .I semid
  98 で指定されたセマフォ集合の選択されたセマフォに対して操作を行う。
  99 .I sops
 100 は
 101 .I nsops
 102 個の要素の配列を指し、配列の各要素は個々のセマフォに
 103 対する操作を示す。その型は
 104 .I struct sembuf
 105 で、次のメンバを持つ:
 106 .sp
 107 .in +4n
 108 .nf
 109 unsigned short sem_num;  /* セマフォ番号 */
 110 short          sem_op;   /* セマフォ操作 */
 111 short          sem_flg;  /* 操作フラグ */
 112 .sp
 113 .in -4n
 114 .fi
 115 .I sem_flg
 116 には
 117 .B IPC_NOWAIT
 118 と
 119 .B SEM_UNDO
 120 が設定できる。
 121 .B SEM_UNDO
 122 が指定された操作は、そのプロセスが終了した時に自動的に取り消される。
 123 .PP
 124 .I sops
 125 に含まれる操作の集合は、
 126 .I "配列の順序"
 127 で、
 128 .I アトミックに
 129 実行される。
 130 すなわち、全ての操作が完全に実行されるか、全く実行されないかの
 131 どちらかとなる。
 132
 133 全ての操作が直ちに実行できない場合のこのシステムコールの振る舞いは
 134 個々の操作の
 135 .I sem_flg
 136 フィールドに
 137 .B IPC_NOWAIT
 138 が存在するかによって決まり、後述のようになる。
 139
 140 それぞれの操作はセマフォ集合の
 141 .IR sem_num 番目
 142 のセマフォに対して実行される。セマフォ集合の最初のセマフォには
 143 番号 0 が振られる。
 144 そして操作は三種類あり、
 145 .I sem_op
 146 の値で区別される。
 147 .PP
 148 .I sem_op
 149 が正の整数の場合、操作としてその値をセマフォの値
 150 .RI ( semval )
 151 に加える。さらにこの操作に
 152 .B SEM_UNDO
 153 が指定されている場合は、システムはこのセマフォの プロセス・アンドゥ数
 154 .RI ( semadj )
 155 を更新する。
 156 この操作は必ず実行でき、プロセスの停止は起こらない。
 157 呼び出し元プロセスは対象のセマフォ集合を変更する許可がなければならない。
 158 .PP
 159 .I sem_op
 160 が 0 の場合、「ゼロまで待つ」操作である。この場合、プロセスは
 161 そのセマフォ集合に対する読み込み許可がなければならない。
 162 .I semval
 163 が 0 ならば、操作は直ちに行われる。
 164 .I semval
 165 が 0 でない場合、
 166 .I sem_flg
 167 に
 168 .B IPC_NOWAIT
 169 が指定されていれば、
 170 .BR semop ()
 171 は失敗し、
 172 .B errno
 173 に
 174 .B EAGAIN
 175 が設定される (このとき
 176 .I sops
 177 に対する操作は全く実行されない)。
 178 .I sem_flg
 179 に
 180 .B IPC_NOWAIT
 181 が指定されていない場合、
 182 .I semzcnt
 183 (セマフォ値が 0 になるのを待っているプロセスの数) を 1 増加させて、
 184 以下のいずれかが起こるまでプロセスを停止 (sleep) する。
 185 .IP \(bu 3
 186 .I semval
 187 が 0 になった: このとき
 188 .I semzcnt
 189 の値は 1 減算される。
 190 .IP \(bu
 191 セマフォ集合が削除された: このとき
 192 .BR semop ()
 193 は失敗し、
 194 .I errno
 195 に
 196 .B EIDRM
 197 が設定される。
 198 .IP \(bu
 199 呼び出し元プロセスがシグナルを捕獲した: このとき
 200 .I semzcnt
 201 の値は 1 減算され、
 202 .BR semop ()
 203 は失敗し
 204 .I errno
 205 に
 206 .B EINTR
 207 が設定される。
 208 .IP \(bu
 209 .\" motoki: semop () は semtimedop () の間違い？
 210 .BR semtimedop ()
 211 の
 212 .I timeout
 213 で指定された制限時間が経過した: このとき
 214 .BR semtimedop ()
 215 は失敗し、
 216 .I errno
 217 に
 218 .B EAGAIN
 219 が設定される。
 220 .PP
 221 .I sem_op
 222 が 0 未満の場合、プロセスにはそのセマフォ集合を変更する許可がなければ
 223 ならない。
 224 .I semval
 225 が
 226 .I sem_op
 227 の絶対値以上の場合は、操作は直ちに実行される:
 228 .I semval
 229 から
 230 .I sem_op
 231 の絶対値が減算される。
 232 さらに、この操作に
 233 .B SEM_UNDO
 234 が指定されている場合は、このセマフォのプロセス・アンドゥ数
 235 .RI ( semadj )
 236 を更新する。
 237 .I semval
 238 が
 239 .I sem_op
 240 の絶対値より小さく、
 241 .I sem_flg
 242 に
 243 .B IPC_NOWAIT
 244 が指定された場合は、
 245 .BR semop ()
 246 は失敗し、
 247 .I errno
 248 に
 249 .B EAGAIN
 250 が設定される (このとき
 251 .I sops
 252 の操作は全く実行されない)。
 253 .B IPC_WAIT
 254 が指定されていなければ、
 255 .I semncnt
 256 (このセマフォの値が増加するのを待っているプロセス数のカウンタ)
 257 を 1 増加させて、以下のいずれかが起こるまでプロセスを停止 (sleep) する。
 258 .IP \(bu 3
 259 .I semval
 260 が
 261 .I sem_op
 262 の絶対値以上になった: このとき
 263 .I semncnt
 264 が 1 減算され、
 265 .I semval
 266 から
 267 .I sem_op
 268 の絶対値が引かれる。
 269 この操作に
 270 .B SEM_UNDO
 271 が指定されていた場合にはこのセマフォのプロセス・アンドゥ数
 272 .RI ( semadj )
 273 も更新する。
 274 .IP \(bu
 275 セマフォ集合がシステムから削除された: このとき
 276 .BR semop ()
 277 は失敗し
 278 .I errno
 279 に
 280 .B EIDRM
 281 が設定される。
 282 .IP \(bu
 283 呼び出したプロセスがシグナルを捕獲した: このとき
 284 .I semncnt
 285 が 1 減算され、
 286 .BR semop ()
 287 は失敗し
 288 .I errno
 289 に
 290 .B EINTR
 291 が設定される。
 292 .IP \(bu
 293 .\" motoki: the system call は semtimedop () のこと？
 294 .BR semtimedop ()
 295 の
 296 .I timeout
 297 で指定された制限時間が経過した: このとき
 298 .BR semtimedop ()
 299 は失敗し、
 300 .I errno
 301 に
 302 .B EAGAIN
 303 が設定される。
 304 .PP
 305 操作が成功した場合、
 306 .I sops
 307 が指す配列によって操作対象となった各セマフォの
 308 .I sempid
 309 メンバーには呼び出したプロセスのプロセス ID が設定される。
 310 さらに
 311 .I sem_otime
 312 .\" と
 313 .\" .I sem_ctime
 314 に現在時刻が設定される。
 315 .PP
 316 .BR semtimedop ()
 317 関数の振る舞いは
 318 .BR semop ()
 319 と全く同じだが、
 320 呼び出し元プロセスが停止する場合、停止期間の上限が
 321 .I timeout
 322 引き数の指す
 323 .I timespec
 324 構造体で指定された時間となる点だけが異なる。
 325 指定した制限時間に達した場合は、
 326 .BR semtimedop ()
 327 は失敗し、
 328 .I errno
 329 に
 330 .B EAGAIN
 331 が設定される
 332 (このとき
 333 .I sops
 334 の操作は実行されない)。
 335 .I timeout
 336 引き数が NULL の場合、
 337 .BR semtimedop ()
 338 関数の振る舞いは
 339 .BR semop ()
 340 関数と全く同じになる。
 341 .SH 返り値
 342 成功した場合、
 343 .BR semop ()
 344 と
 345 .BR semtimedop ()
 346 は 0 を返す。そうでなければ \-1 を返し、
 347 エラーを示す
 348 .I errno
 349 を設定する。
 350 .SH エラー
 351 失敗した場合、
 352 .I errno
 353 に以下のどれかが設定される:
 354 .TP
 355 .B E2BIG
 356 .I nsops
 357 引き数が
 358 .B SEMOPM
 359 より大きい。
 360 .B SEMOPM
 361 は一回のシステムコールで許される操作の最大個数である。
 362 .TP
 363 .B EACCES
 364 呼び出し元プロセスには指定されたセマフォ操作を行うのに
 365 必要なアクセス許可がなく、
 366 .B CAP_IPC_OWNER
 367 ケーパビリティもない。
 368 .TP
 369 .B EAGAIN
 370 操作を直ちに処理することができず、かつ
 371 .I sem_flg
 372 に
 373 .B IPC_NOWAIT
 374 が指定されているか
 375 .I timeout
 376 で指定された制限時間が経過した。
 377 .TP
 378 .B EFAULT
 379 引き数
 380 .I sops
 381 か
 382 .I timeout
 383 が指しているアドレスにアクセスできない。
 384 .TP
 385 .B EFBIG
 386 ある操作で、
 387 .I sem_num
 388 の値が 0 未満か、集合内のセマフォの数以上である。
 389 .TP
 390 .B EIDRM
 391 セマフォ集合が削除された。
 392 .TP
 393 .B EINTR
 394 このシステムコールで停止している時にプロセスがシグナルを捕獲した。
 395 .BR single (7)
 396 参照。
 397 .TP
 398 .B EINVAL
 399 セマフォ集合が存在しないか、
 400 .I semid
 401 が 0 未満であるか、
 402 .I nsops
 403 が正の数でない。
 404 .TP
 405 .B ENOMEM
 406 ある操作で
 407 .I sem_flg
 408 に
 409 .B SEM_UNDO
 410 が指定されたが、システムにアンドゥ構造体に割り当てる十分なメモリがない。
 411 .TP
 412 .B ERANGE
 413 ある操作で
 414 .I sem_op+semval
 415 が
 416 .B SEMVMX
 417 より大きい。
 418 .B SEMVMX
 419 は
 420 .I semval
 421 の最大値で、その値は実装依存である。
 422 .SH バージョン
 423 .BR semtimedop ()
 424 は Linux 2.5.52 で初めて登場し、
 425 それからカーネル 2.4.22 にも移植された。
 426 .BR semtimedop ()
 427 の glibc でのサポートはバージョン 2.3.3 で初めて登場した。
 428 .SH 準拠
 429 SVr4, POSIX.1-2001.
 430 .\" SVr4 には、追加で EINVAL, EFBIG, ENOSPC のエラー状態についての
 431 .\" 記述がある。
 432 .SH 注意
 433 あるプロセスの
 434 .I sem_undo
 435 構造体は
 436 .BR fork (2)
 437 で生成された子プロセスには継承されないが、
 438 .BR execve (2)
 439 システムコールの場合は継承される。
 440 .PP
 441 .BR semop ()
 442 はシグナルハンドラによって中断された後に、
 443 決して自動的に再開することはない。
 444 たとえシグナルハンドラの設定時に
 445 .B SA_RESTART
 446 フラグがセットされていても再開することはない
 447 .PP
 448 .I semadj
 449 はプロセスごとの整数で、
 450 .B SEM_UNDO
 451 フラグを設定して実行された全てのセマフォ操作の(負数の)カウンタである。
 452 .BR semctl (2)
 453 に
 454 .B SETVAL
 455 または
 456 .B SETALL
 457 を指定し、セマフォの値が
 458 直接設定された場合には、全てのプロセスにおいて対応する
 459 .I semadj
 460 の値がクリアされる。
 461 .PP
 462 あるセマフォの \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, \fIsemnct\fP
 463 の値はいずれも、適切な操作を指定して
 464 .BR semctl (2)
 465 を呼び出すことで取得できる。
 466 .PP
 467 セマフォ集合のリソースに関する制限のうち、
 468 .BR semop ()
 469 に影響を及ぼすものを以下に挙げる:
 470 .TP
 471 .B SEMOPM
 472 一回の
 473 .BR semop ()
 474 で許される操作の最大数 (32)。
 475 (Linux では、この制限値は
 476 .I /proc/sys/kernel/sem
 477 の第3フィールドに対応し、読み出しも変更もできる)。
 478 .\" この /proc ファイルは Linux 2.2 以前では利用できない -- MTK
 479 .TP
 480 .B SEMVMX
 481 .I semval
 482 が取り得る最大値: 実装依存 (32767)。
 483 .PP
 484 以下の値に関しては実装依存の制限はない。
 485 終了時の調整 (adjust on exit) の最大値
 486 .RB ( SEMAEM )、
 487 システム全体のアンドゥ構造体の最大数
 488 .RB ( SEMMNU )、
 489 プロセスあたりのアンドゥ構造体の最大数。
 490 .SH バグ
 491 プロセスが終了する際、プロセスに対応する
 492 .I semadj
 493 の集合を使って、
 494 .B SEM_UNDO
 495 フラグ付きで実行された全てのセマフォ操作の影響を取り消す。
 496 これによりある問題が発生する: これらのセマフォの調整を行っていると、
 497 中にはセマフォの値が 0 未満の値にしようとする場合が出てくる。
 498 このような場合、どのように実装するべきか?
 499 ひとつの考えられる手法は、全てのセマフォ調整が実行されるまで
 500 停止することである。しかし、この方法ではプロセスの終了が
 501 長時間にわたって停止されることがあるので望ましくない。
 502 しかもどれくらい長時間になるかは分からない。
 503 別の選択肢として、このようなセマフォ調整を完全に無視してしまう方法がある
 504 (これはセマフォ操作として
 505 .B IPC_NOWAIT
 506 が指定するのと少し似ている)。
 507 Linux は第三の手法を採用している: セマフォの値を出来るだけ (つまり
 508 0 まで) 減少させて、プロセスの終了を直ちに続行できるようにしている。
 509
 510 カーネル 2.6.x (x <= 10) には、ある状況においてセマフォ値が 0 になるのを
 511 待っているプロセスが、セマフォ値が実際に 0 になったときに起床 (wake up)
 512 されない、というバグがある。このバグはカーネル 2.6.11 で修正されている。
 513 .\" バグレポート:
 514 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2
 515 .\" 修正:
 516 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2
 517 .SH 例
 518 以下の部分的なコードは、
 519 セマフォ 0 の値が 0 になるのを待ってから、
 520 セマフォの値を 1 加算する処理を、
 521 .BR semop ()
 522 を使ってアトミック (atomically) に行う。
 523 .nf
 524
 525     struct sembuf sops[2];
 526     int semid;
 527
 528     /* Code to set \fIsemid\fP omitted */
 529
 530     sops[0].sem_num = 0;        /* Operate on semaphore 0 */
 531     sops[0].sem_op = 0;         /* Wait for value to equal 0 */
 532     sops[0].sem_flg = 0;
 533
 534     sops[1].sem_num = 0;        /* Operate on semaphore 0 */
 535     sops[1].sem_op = 1;         /* Increment value by one */
 536     sops[1].sem_flg = 0;
 537
 538     if (semop(semid, sops, 2) == \-1) {
 539         perror("semop");
 540         exit(EXIT_FAILURE);
 541     }
 542 .fi
 543 .SH 関連項目
 544 .BR semctl (2),
 545 .BR semget (2),
 546 .BR sigaction (2),
 547 .BR capabilities (7),
 548 .BR sem_overview (7),
 549 .BR svipc (7),
 550 .BR time (7)