release/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 .TH SEMOP 2 2012\-08\-27 Linux "Linux Programmer's Manual"
  41 .SH 名前
  42 semop, semtimedop \- セマフォの操作
  43 .SH 書式
  44 .nf
  45 \fB#include <sys/types.h>\fP
  46 \fB#include <sys/ipc.h>\fP
  47 \fB#include <sys/sem.h>\fP
  48 .sp
  49 \fBint semop(int \fP\fIsemid\fP\fB, struct sembuf *\fP\fIsops\fP\fB, unsigned \fP\fInsops\fP\fB);\fP
  50 .sp
  51 \fBint semtimedop(int \fP\fIsemid\fP\fB, struct sembuf *\fP\fIsops\fP\fB, unsigned \fP\fInsops\fP\fB,\fP
  52 \fB               struct timespec *\fP\fItimeout\fP\fB);\fP
  53 .fi
  54 .sp
  55 .in -4n
  56 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  57 .in
  58 .sp
  59 \fBsemtimedop\fP(): _GNU_SOURCE
  60 .SH 説明
  61 セマフォ集合 (semaphore set) のメンバーの各セマフォは 以下の関連情報を持っている:
  62 .sp
  63 .in +4n
  64 .nf
  65 unsigned short  semval;   /* semaphore value */
  66 unsigned short  semzcnt;  /* # waiting for zero */
  67 unsigned short  semncnt;  /* # waiting for increase */
  68 pid_t           sempid;   /* ID of process that did last op */
  69 .sp
  70 .in -4n
  71 .fi
  72 \fBsemop\fP()  は \fIsemid\fP で指定されたセマフォ集合の選択されたセマフォに対して操作を行う。 \fIsops\fP は \fInsops\fP
  73 個の要素の配列を指し、配列の各要素は個々のセマフォに 対する操作を示す。その型は \fIstruct sembuf\fP で、次のメンバを持つ:
  74 .sp
  75 .in +4n
  76 .nf
  77 unsigned short sem_num;  /* セマフォ番号 */
  78 short          sem_op;   /* セマフォ操作 */
  79 short          sem_flg;  /* 操作フラグ */
  80 .sp
  81 .in -4n
  82 .fi
  83 \fIsem_flg\fP には \fBIPC_NOWAIT\fP と \fBSEM_UNDO\fP が設定できる。 \fBSEM_UNDO\fP
  84 が指定された操作は、そのプロセスが終了した時に自動的に取り消される。
  85 .PP
  86 \fIsops\fP に含まれる操作の集合は、 \fI配列の順序\fP で、 \fIアトミックに\fP 実行される。
  87 すなわち、全ての操作が完全に実行されるか、全く実行されないかの どちらかとなる。 全ての操作が直ちに実行できない場合のこのシステムコールの振る舞いは
  88 個々の操作の \fIsem_flg\fP フィールドに \fBIPC_NOWAIT\fP が存在するかによって決まり、後述のようになる。
  89
  90 それぞれの操作はセマフォ集合の \fIsem_num\fP番目 のセマフォに対して実行される。セマフォ集合の最初のセマフォには 番号 0 が振られる。
  91 そして操作は三種類あり、 \fIsem_op\fP の値で区別される。
  92 .PP
  93 If \fIsem_op\fP is a positive integer, the operation adds this value to the
  94 semaphore value (\fIsemval\fP).  Furthermore, if \fBSEM_UNDO\fP is specified for
  95 this operation, the system updates the undo count (\fIsemadj\fP)  for this
  96 semaphore.  This operation can always proceed\(emit never forces a thread to
  97 wait.  The calling process must have alter permission on the semaphore set.
  98 .PP
  99 If \fIsem_op\fP is zero, the process must have read permission on the semaphore
 100 set.  This is a "wait\-for\-zero" operation: if \fIsemval\fP is zero, the
 101 operation can immediately proceed.  Otherwise, if \fBIPC_NOWAIT\fP is specified
 102 in \fIsem_flg\fP, \fBsemop\fP()  fails with \fIerrno\fP set to \fBEAGAIN\fP (and none of
 103 the operations in \fIsops\fP is performed).  Otherwise \fIsemzcnt\fP (the count of
 104 threads waiting until this semaphore's value becomes zero)  is incremented
 105 by one and the thread sleeps until one of the following occurs:
 106 .IP \(bu 3
 107 \fIsemval\fP が 0 になった: このとき \fIsemzcnt\fP の値は 1 減算される。
 108 .IP \(bu
 109 セマフォ集合が削除された: このとき \fBsemop\fP()  は失敗し、 \fIerrno\fP に \fBEIDRM\fP が設定される。
 110 .IP \(bu
 111 The calling thread catches a signal: the value of \fIsemzcnt\fP is decremented
 112 and \fBsemop\fP()  fails, with \fIerrno\fP set to \fBEINTR\fP.
 113 .IP \(bu
 114 \fBsemtimedop\fP()  の \fItimeout\fP で指定された制限時間が経過した: このとき \fBsemtimedop\fP()  は失敗し、
 115 \fIerrno\fP に \fBEAGAIN\fP が設定される。
 116 .PP
 117 If \fIsem_op\fP is less than zero, the process must have alter permission on
 118 the semaphore set.  If \fIsemval\fP is greater than or equal to the absolute
 119 value of \fIsem_op\fP, the operation can proceed immediately: the absolute
 120 value of \fIsem_op\fP is subtracted from \fIsemval\fP, and, if \fBSEM_UNDO\fP is
 121 specified for this operation, the system updates the undo count (\fIsemadj\fP)
 122 for this semaphore.  If the absolute value of \fIsem_op\fP is greater than
 123 \fIsemval\fP, and \fBIPC_NOWAIT\fP is specified in \fIsem_flg\fP, \fBsemop\fP()  fails,
 124 with \fIerrno\fP set to \fBEAGAIN\fP (and none of the operations in \fIsops\fP is
 125 performed).  Otherwise \fIsemncnt\fP (the counter of threads waiting for this
 126 semaphore's value to increase)  is incremented by one and the thread sleeps
 127 until one of the following occurs:
 128 .IP \(bu 3
 129 \fIsemval\fP becomes greater than or equal to the absolute value of \fIsem_op\fP,
 130 at which time the value of \fIsemncnt\fP is decremented, the absolute value of
 131 \fIsem_op\fP is subtracted from \fIsemval\fP and, if \fBSEM_UNDO\fP is specified for
 132 this operation, the system updates the undo count (\fIsemadj\fP)  for this
 133 semaphore.
 134 .IP \(bu
 135 セマフォ集合がシステムから削除された: このとき \fBsemop\fP()  は失敗し \fIerrno\fP に \fBEIDRM\fP が設定される。
 136 .IP \(bu
 137 The calling thread catches a signal: the value of \fIsemncnt\fP is decremented
 138 and \fBsemop\fP()  fails, with \fIerrno\fP set to \fBEINTR\fP.
 139 .IP \(bu
 140 \fBsemtimedop\fP()  の \fItimeout\fP で指定された制限時間が経過した: このとき \fBsemtimedop\fP()  は失敗し、
 141 \fIerrno\fP に \fBEAGAIN\fP が設定される。
 142 .PP
 143 .\" and
 144 .\" .I sem_ctime
 145 On successful completion, the \fIsempid\fP value for each semaphore specified
 146 in the array pointed to by \fIsops\fP is set to the caller's process ID.  In
 147 addition, the \fIsem_otime\fP is set to the current time.
 148 .PP
 149 \fBsemtimedop\fP()  behaves identically to \fBsemop\fP()  except that in those
 150 cases where the calling thread would sleep, the duration of that sleep is
 151 limited by the amount of elapsed time specified by the \fItimespec\fP structure
 152 whose address is passed in the \fItimeout\fP argument.  (This sleep interval
 153 will be rounded up to the system clock granularity, and kernel scheduling
 154 delays mean that the interval may overrun by a small amount.)  If the
 155 specified time limit has been reached, \fBsemtimedop\fP()  fails with \fIerrno\fP
 156 set to \fBEAGAIN\fP (and none of the operations in \fIsops\fP is performed).  If
 157 the \fItimeout\fP argument is NULL, then \fBsemtimedop\fP()  behaves exactly like
 158 \fBsemop\fP().
 159 .SH 返り値
 160 成功した場合、 \fBsemop\fP()  と \fBsemtimedop\fP()  は 0 を返す。そうでなければ \-1 を返し、 エラーを示す
 161 \fIerrno\fP を設定する。
 162 .SH エラー
 163 失敗した場合、 \fIerrno\fP に以下のどれかが設定される:
 164 .TP
 165 \fBE2BIG\fP
 166 \fInsops\fP 引き数が \fBSEMOPM\fP より大きい。 \fBSEMOPM\fP は一回のシステムコールで許される操作の最大個数である。
 167 .TP
 168 \fBEACCES\fP
 169 呼び出し元プロセスには指定されたセマフォ操作を行うのに 必要なアクセス許可がなく、 \fBCAP_IPC_OWNER\fP ケーパビリティもない。
 170 .TP
 171 \fBEAGAIN\fP
 172 操作を直ちに処理することができず、かつ \fIsem_flg\fP に \fBIPC_NOWAIT\fP が指定されているか \fItimeout\fP
 173 で指定された制限時間が経過した。
 174 .TP
 175 \fBEFAULT\fP
 176 引き数 \fIsops\fP か \fItimeout\fP が指しているアドレスにアクセスできない。
 177 .TP
 178 \fBEFBIG\fP
 179 ある操作で、 \fIsem_num\fP の値が 0 未満か、集合内のセマフォの数以上である。
 180 .TP
 181 \fBEIDRM\fP
 182 セマフォ集合が削除された。
 183 .TP
 184 \fBEINTR\fP
 185 While blocked in this system call, the thread caught a signal; see
 186 \fBsignal\fP(7).
 187 .TP
 188 \fBEINVAL\fP
 189 セマフォ集合が存在しないか、 \fIsemid\fP が 0 未満であるか、 \fInsops\fP が正の数でない。
 190 .TP
 191 \fBENOMEM\fP
 192 ある操作で \fIsem_flg\fP に \fBSEM_UNDO\fP が指定されたが、システムにアンドゥ構造体に割り当てる十分なメモリがない。
 193 .TP
 194 \fBERANGE\fP
 195 ある操作で \fIsem_op+semval\fP が \fBSEMVMX\fP より大きい。 \fBSEMVMX\fP は \fIsemval\fP
 196 の最大値で、その値は実装依存である。
 197 .SH バージョン
 198 \fBsemtimedop\fP()  は Linux 2.5.52 で初めて登場し、 それからカーネル 2.4.22 にも移植された。
 199 \fBsemtimedop\fP()  の glibc でのサポートはバージョン 2.3.3 で初めて登場した。
 200 .SH 準拠
 201 .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC.
 202 SVr4, POSIX.1\-2001.
 203 .SH 注意
 204 .\" Like Linux, the FreeBSD man pages still document
 205 .\" the inclusion of these header files.
 206 The inclusion of \fI<sys/types.h>\fP and \fI<sys/ipc.h>\fP isn't
 207 required on Linux or by any version of POSIX.  However, some old
 208 implementations required the inclusion of these header files, and the SVID
 209 also documented their inclusion.  Applications intended to be portable to
 210 such old systems may need to include these header files.
 211
 212 あるプロセスの \fIsem_undo\fP 構造体は \fBfork\fP(2)  で生成された子プロセスには継承されないが、 \fBexecve\fP(2)
 213 システムコールの場合は継承される。
 214 .PP
 215 \fBsemop\fP()  はシグナルハンドラによって中断された後に、 決して自動的に再開することはない。 たとえシグナルハンドラの設定時に
 216 \fBSA_RESTART\fP フラグがセットされていても再開することはない
 217 .PP
 218 \fIsemadj\fP はプロセスごとの整数で、 \fBSEM_UNDO\fP フラグを設定して実行された全てのセマフォ操作の(負数の)カウンタである。
 219 \fBsemctl\fP(2)  に \fBSETVAL\fP または \fBSETALL\fP を指定し、セマフォの値が
 220 直接設定された場合には、全てのプロセスにおいて対応する \fIsemadj\fP の値がクリアされる。
 221 .PP
 222 あるセマフォの \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, \fIsemnct\fP の値はいずれも、適切な操作を指定して
 223 \fBsemctl\fP(2)  を呼び出すことで取得できる。
 224 .PP
 225 セマフォ集合のリソースに関する制限のうち、 \fBsemop\fP()  に影響を及ぼすものを以下に挙げる:
 226 .TP
 227 \fBSEMOPM\fP
 228 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 229 一回の \fBsemop\fP()  で許される操作の最大数 (32)。 (Linux では、この制限値は \fI/proc/sys/kernel/sem\fP
 230 の第3フィールドに対応し、読み出しも変更もできる)。
 231 .TP
 232 \fBSEMVMX\fP
 233 \fIsemval\fP が取り得る最大値: 実装依存 (32767)。
 234 .PP
 235 以下の値に関しては実装依存の制限はない。 終了時の調整 (adjust on exit) の最大値 (\fBSEMAEM\fP)、
 236 システム全体のアンドゥ構造体の最大数 (\fBSEMMNU\fP)、 プロセスあたりのアンドゥ構造体の最大数。
 237 .SH バグ
 238 プロセスが終了する際、プロセスに対応する \fIsemadj\fP の集合を使って、 \fBSEM_UNDO\fP
 239 フラグ付きで実行された全てのセマフォ操作の影響を取り消す。 これによりある問題が発生する: これらのセマフォの調整を行っていると、 中にはセマフォの値が
 240 0 未満の値にしようとする場合が出てくる。 このような場合、どのように実装するべきか? ひとつの考えられる手法は、全てのセマフォ調整が実行されるまで
 241 停止することである。しかし、この方法ではプロセスの終了が 長時間にわたって停止されることがあるので望ましくない。
 242 しかもどれくらい長時間になるかは分からない。 別の選択肢として、このようなセマフォ調整を完全に無視してしまう方法がある (これはセマフォ操作として
 243 \fBIPC_NOWAIT\fP が指定するのと少し似ている)。 Linux は第三の手法を採用している: セマフォの値を出来るだけ (つまり 0 まで)
 244 減少させて、プロセスの終了を直ちに続行できるようにしている。
 245
 246 .\" The bug report:
 247 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2
 248 .\" the fix:
 249 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2
 250 In kernels 2.6.x, x <= 10, there is a bug that in some circumstances
 251 prevents a thread that is waiting for a semaphore value to become zero from
 252 being woken up when the value does actually become zero.  This bug is fixed
 253 in kernel 2.6.11.
 254 .SH 例
 255 以下の部分的なコードは、 セマフォ 0 の値が 0 になるのを待ってから、 セマフォの値を 1 加算する処理を、 \fBsemop\fP()
 256 を使ってアトミック (atomically) に行う。
 257 .nf
 258
 259     struct sembuf sops[2];
 260     int semid;
 261
 262     /* Code to set \fIsemid\fP omitted */
 263
 264     sops[0].sem_num = 0;        /* Operate on semaphore 0 */
 265     sops[0].sem_op = 0;         /* Wait for value to equal 0 */
 266     sops[0].sem_flg = 0;
 267
 268     sops[1].sem_num = 0;        /* Operate on semaphore 0 */
 269     sops[1].sem_op = 1;         /* Increment value by one */
 270     sops[1].sem_flg = 0;
 271
 272     if (semop(semid, sops, 2) == \-1) {
 273         perror("semop");
 274         exit(EXIT_FAILURE);
 275     }
 276 .fi
 277 .SH 関連項目
 278 \fBclone\fP(2), \fBsemctl\fP(2), \fBsemget\fP(2), \fBsigaction\fP(2),
 279 \fBcapabilities\fP(7), \fBsem_overview\fP(7), \fBsvipc\fP(7), \fBtime\fP(7)
 280 .SH この文書について
 281 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部
 282 である。プロジェクトの説明とバグ報告に関する情報は
 283 http://www.kernel.org/doc/man\-pages/ に書かれている。