draft/man3/sem_wait.3

   1 '\" t
   2 .\" Hey Emacs! This file is -*- nroff -*- source.
   3 .\"
   4 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\"
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\"
  26 .\" Japanese Version Copyright (c) 2006 Akihiro MOTOKI all rights reserved.
  27 .\" Translated 2006-04-18, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  28 .\"
  29 .TH SEM_WAIT 3 2010-02-25 "Linux" "Linux Programmer's Manual"
  30 .\"O .SH NAME
  31 .SH 名前
  32 .\"O sem_wait, sem_timedwait, sem_trywait \- lock a semaphore
  33 sem_wait, sem_timedwait, sem_trywait \- セマフォをロックする
  34 .\"O .SH SYNOPSIS
  35 .SH 書式
  36 .nf
  37 .B #include <semaphore.h>
  38 .sp
  39 .BI "int sem_wait(sem_t *" sem );
  40 .sp
  41 .BI "int sem_trywait(sem_t *" sem );
  42 .sp
  43 .BI "int sem_timedwait(sem_t *" sem ", const struct timespec *" abs_timeout );
  44 .fi
  45 .sp
  46 .sp
  47 .\"O Link with \fI\-lrt\fP or \fI\-pthread\fP.
  48 \fI\-lrt\fP または \fI\-pthread\fP でリンクする。
  49 .in -4n
  50 .\"O Feature Test Macro Requirements for glibc (see
  51 .\"O .BR feature_test_macros (7)):
  52 glibc 向けの機能検査マクロの要件
  53 .RB ( feature_test_macros (7)
  54 参照):
  55 .in
  56 .sp
  57 .BR sem_timedwait ():
  58 _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
  59 .\"O .SH DESCRIPTION
  60 .SH 説明
  61 .\"O .BR sem_wait ()
  62 .\"O decrements (locks) the semaphore pointed to by
  63 .\"O .IR sem .
  64 .\"O If the semaphore's value is greater than zero,
  65 .\"O then the decrement proceeds, and the function returns, immediately.
  66 .\"O If the semaphore currently has the value zero,
  67 .\"O then the call blocks until either it becomes possible to perform
  68 .\"O the decrement (i.e., the semaphore value rises above zero),
  69 .\"O or a signal handler interrupts the call.
  70 .BR sem_wait ()
  71 は
  72 .I sem
  73 が指すセマフォの値を 1 減らす (ロックする)。
  74 セマフォの値が 0 より大きい場合、減算が実行され、関数は直ちに復帰する。
  75 セマフォの現在値が 0 の場合には、減算を実行できるようになる
  76 (つまり、セマフォの値が 0 より大きな値になる) まで、もしくは
  77 シグナルハンドラによって呼び出しが中断されるまで、
  78 関数呼び出しは停止 (block) する。
  79
  80 .\"O .BR sem_trywait ()
  81 .\"O is the same as
  82 .\"O .BR sem_wait (),
  83 .\"O except that if the decrement cannot be immediately performed,
  84 .\"O then call returns an error
  85 .\"O .RI ( errno
  86 .\"O set to
  87 .\"O .BR EAGAIN )
  88 .\"O instead of blocking.
  89 .BR sem_trywait ()
  90 は
  91 .BR sem_wait ()
  92 と同じだが、セマフォ値の減算をすぐに実行できなかった場合に、
  93 停止 (block) するのではなくエラーで復帰する
  94 .RI ( errno
  95 に
  96 .B EAGAIN
  97 がセットされる) 点が異なる。
  98
  99 .\"O .BR sem_timedwait ()
 100 .\"O is the same as
 101 .\"O .BR sem_wait (),
 102 .\"O except that
 103 .\"O .I abs_timeout
 104 .\"O specifies a limit on the amount of time that the call
 105 .\"O should block if the decrement cannot be immediately performed.
 106 .\"O The
 107 .\"O .I abs_timeout
 108 .\"O argument points to a structure that specifies an absolute timeout
 109 .\"O in seconds and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
 110 .\"O This structure is defined as follows:
 111 .BR sem_timedwait ()
 112 は
 113 .BR sem_wait ()
 114 と同じだが、セマフォ値の減算をすぐに実行できなかった場合に
 115 関数呼び出しが停止する時間の上限を
 116 .I abs_timeout
 117 で指定する点が異なる。
 118 .I abs_timeout
 119 引き数は、タイムアウト時刻を指定する構造体へのポインタである。
 120 この構造体には、タイムアウト時刻を時刻紀元 (Epoch;
 121 1970-01-01 00:00:00 +0000 (UTC)) からの
 122 経過時間 (秒＋ナノ秒) で指定する。
 123 構造体は以下のように定義されている:
 124
 125 .nf
 126 .in +4n
 127 struct timespec {
 128     time_t tv_sec;      /* Seconds */
 129     long   tv_nsec;     /* Nanoseconds [0 .. 999999999] */
 130 };
 131 .in
 132 .fi
 133 .PP
 134 .\"O If the timeout has already expired by the time of the call,
 135 .\"O and the semaphore could not be locked immediately,
 136 .\"O then
 137 .\"O .BR sem_timedwait ()
 138 .\"O fails with a timeout error
 139 .\"O .RI ( errno
 140 .\"O set to
 141 .\"O .BR ETIMEDOUT ).
 142 関数呼び出し時点ですでにタイムアウトに指定した時刻が過ぎており、
 143 かつセマフォをすぐにロックできなかった場合は、
 144 .BR sem_timedwait ()
 145 はタイムアウトエラー
 146 .RI ( errno
 147 に
 148 .B ETIMEDOUT
 149 がセットされる) で失敗する。
 150
 151 .\"O If the operation can be performed immediately, then
 152 .\"O .BR sem_timedwait ()
 153 .\"O never fails with a timeout error, regardless of the value of
 154 .\"O .IR abs_timeout .
 155 .\"O Furthermore, the validity of
 156 .\"O .I abs_timeout
 157 .\"O is not checked in this case.
 158 セマフォ操作がすぐに実行できるときは、
 159 .I abs_timeout
 160 がどんな値であっても
 161 .BR sem_timedwait ()
 162 が失敗することは決してない。さらにいうと、この場合には
 163 .I abs_timeout
 164 の正当性の検査は行われない。
 165 .\"O .SH RETURN VALUE
 166 .SH 返り値
 167 .\"O All of these functions return 0 on success;
 168 .\"O on error, the value of the semaphore is left unchanged,
 169 .\"O \-1 is returned, and
 170 .\"O .I errno
 171 .\"O is set to indicate the error.
 172 成功すると、これらの関数は 0 を返す。
 173 エラーの場合、セマフォの値を変更せずに、\-1 を返し、
 174 .I errno
 175 にエラーを示す値をセットする。
 176 .\"O .SH ERRORS
 177 .SH エラー
 178 .TP
 179 .B EINTR
 180 .\"O The call was interrupted by a signal handler; see
 181 .\"O .BR signal (7).
 182 呼び出しはシグナルハンドラにより中断された。
 183 .BR signal (7)
 184 参照。
 185 .TP
 186 .B EINVAL
 187 .\"O .I sem
 188 .\"O is not a valid semaphore.
 189 .I sem
 190 は有効なセマフォでない。
 191 .PP
 192 .\"O The following additional error can occur for
 193 .\"O .BR sem_trywait ():
 194 .BR sem_trywait ()
 195 の場合には、上記に加えて以下のエラーも起こる。
 196 .TP
 197 .B EAGAIN
 198 .\"O The operation could not be performed without blocking (i.e., the
 199 .\"O semaphore currently has the value zero).
 200 停止 (block) せずにロック操作を完了できなかった (つまり、
 201 セマフォの現在の値が 0 であった)。
 202 .PP
 203 .\"O The following additional errors can occur for
 204 .\"O .BR sem_timedwait ():
 205 .BR sem_timedwait ()
 206 の場合、以下のエラーも起こる。
 207 .TP
 208 .B EINVAL
 209 .\"O The value of
 210 .\"O .I abs_timeout.tv_nsecs
 211 .\"O is less than 0, or greater than or equal to 1000 million.
 212 .I abs_timeout.tv_nsecs
 213 の値が 0 未満、もしくは 1,000,000,000 以上である。
 214 .TP
 215 .B ETIMEDOUT
 216 .\"O The call timed out before the semaphore could be locked.
 217 セマフォのロックに成功する前に時間切れとなった。
 218 .\"O .\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition
 219 .\"O .\" was detected", but this does not occur on Linux(?).
 220 .\" POSIX.1-2001 ではエラーとして EDEADLK も用意している。
 221 .\" これはデッドロック条件を検出したことを示すものだが、
 222 .\" Linux で発生することはない(?)
 223 .\"O .SH CONFORMING TO
 224 POSIX.1-2001.
 225 .\"O .SH NOTES
 226 .SH 注意
 227 .\"O A signal handler always interrupts a blocked call to
 228 .\"O one of these functions, regardless of the use of the
 229 .\"O .BR sigaction (2)
 230 .\"O .B SA_RESTART
 231 .\"O flag.
 232 シグナルハンドラは、
 233 .BR sigaction (2)
 234 の
 235 .B SA_RESTART
 236 フラグを使用しているかどうかに関わらず、これらの関数の呼び出しが
 237 停止している場合、シグナルハンドラにより常に中断される。
 238 .\"O .\" sem_wait() is always interrupted on most other implementations,
 239 .\"O .\" but on FreeBSD 5.4 SA_RESTART does cause restarting.
 240 .\" sem_wait() は他のほとんどの実装では常に中断されるが、
 241 .\" FreeBSD 5.4 では SA_RESTART を指定しておくと実行が再開される。
 242 .\"O .SH EXAMPLE
 243 .SH 例
 244 .PP
 245 .\"O The (somewhat trivial) program shown below operates on an
 246 .\"O unnamed semaphore.
 247 .\"O The program expects two command-line arguments.
 248 .\"O The first argument specifies a seconds value that is used to
 249 .\"O set an alarm timer to generate a
 250 .\"O .B SIGALRM
 251 .\"O signal.
 252 .\"O This handler performs a
 253 .\"O .BR sem_post (3)
 254 .\"O to increment the semaphore that is being waited on in
 255 .\"O .I main()
 256 .\"O using
 257 .\"O .BR sem_timedwait ().
 258 .\"O The second command-line argument specifies the length
 259 .\"O of the timeout, in seconds, for
 260 .\"O .BR sem_timedwait ().
 261 .\"O The following shows what happens on two different runs of the program:
 262 以下に示す (ちょっとした) プログラムは名前なしセマフォの操作を行う。
 263 プログラムはコマンドライン引き数を 2 つ取る。
 264 最初の引き数には、
 265 .B SIGALRM
 266 シグナルを生成するためのアラームタイマーの設定に使われる値を
 267 秒単位で指定する。このシグナルハンドラは、
 268 .I main()
 269 内で
 270 .BR sem_timedwait ()
 271 を使って待っているセマフォを、
 272 .BR sem_post (3)
 273 を使って加算する。
 274 2番目の引き数には、
 275 .BR sem_timedwait ()
 276 に渡すタイムアウトまでの時間を秒単位で指定する。
 277
 278 .in +4n
 279 .nf
 280 .RB "$" " ./a.out 2 3"
 281 About to call sem_timedwait()
 282 sem_post() from handler
 283 sem_getvalue() from handler; value = 1
 284 sem_timedwait() succeeded
 285 .RB "$" " ./a.out 2 1"
 286 About to call sem_timedwait()
 287 sem_timedwait() timed out
 288 .fi
 289 .in
 290 .\"O .SS Program source
 291 .SS プログラムのソース
 292 \&
 293 .nf
 294 #include <unistd.h>
 295 #include <stdio.h>
 296 #include <stdlib.h>
 297 #include <semaphore.h>
 298 #include <time.h>
 299 #include <assert.h>
 300 #include <errno.h>
 301 #include <signal.h>
 302
 303 sem_t sem;
 304
 305 #define handle_error(msg) \\
 306     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 307
 308 static void
 309 handler(int sig)
 310 {
 311     write(STDOUT_FILENO, "sem_post() from handler\\n", 24);
 312     if (sem_post(&sem) == \-1) {
 313         write(STDERR_FILENO, "sem_post() failed\\n", 18);
 314         _exit(EXIT_FAILURE);
 315     }
 316 }
 317
 318 int
 319 main(int argc, char *argv[])
 320 {
 321     struct sigaction sa;
 322     struct timespec ts;
 323     int s;
 324
 325     if (argc != 3) {
 326         fprintf(stderr, "Usage: %s <alarm\-secs> <wait\-secs>\\n",
 327                 argv[0]);
 328         exit(EXIT_FAILURE);
 329     }
 330
 331     if (sem_init(&sem, 0, 0) == \-1)
 332         handle_error("sem_init");
 333
 334     /* Establish SIGALRM handler; set alarm timer using argv[1] */
 335
 336     sa.sa_handler = handler;
 337     sigemptyset(&sa.sa_mask);
 338     sa.sa_flags = 0;
 339     if (sigaction(SIGALRM, &sa, NULL) == \-1)
 340         handle_error("sigaction");
 341
 342     alarm(atoi(argv[1]));
 343
 344     /* Calculate relative interval as current time plus
 345        number of seconds given argv[2] */
 346
 347     if (clock_gettime(CLOCK_REALTIME, &ts) == \-1)
 348         handle_error("clock_gettime");
 349
 350     ts.tv_sec += atoi(argv[2]);
 351
 352     printf("main() about to call sem_timedwait()\\n");
 353     while ((s = sem_timedwait(&sem, &ts)) == \-1 && errno == EINTR)
 354         continue;       /* Restart if interrupted by handler */
 355
 356     /* Check what happened */
 357
 358     if (s == \-1) {
 359         if (errno == ETIMEDOUT)
 360             printf("sem_timedwait() timed out\\n");
 361         else
 362             perror("sem_timedwait");
 363     } else
 364         printf("sem_timedwait() succeeded\\n");
 365
 366     exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
 367 }
 368 .fi
 369 .\"O .SH "SEE ALSO"
 370 .SH 関連項目
 371 .BR clock_gettime (2),
 372 .BR sem_getvalue (3),
 373 .BR sem_post (3),
 374 .BR sem_overview (7),
 375 .BR time (7)