draft/man3/sem_wait.3

   1 .\" t
   2 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\"*******************************************************************
  27 .\"
  28 .\" This file was generated with po4a. Translate the source file.
  29 .\"
  30 .\"*******************************************************************
  31 .\"
  32 .\" Japanese Version Copyright (c) 2006 Akihiro MOTOKI all rights reserved.
  33 .\" Translated 2006-04-18, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  34 .\"
  35 .TH SEM_WAIT 3 2012\-05\-13 Linux "Linux Programmer's Manual"
  36 .SH 名前
  37 sem_wait, sem_timedwait, sem_trywait \- セマフォをロックする
  38 .SH 書式
  39 .nf
  40 \fB#include <semaphore.h>\fP
  41 .sp
  42 \fBint sem_wait(sem_t *\fP\fIsem\fP\fB);\fP
  43 .sp
  44 \fBint sem_trywait(sem_t *\fP\fIsem\fP\fB);\fP
  45 .sp
  46 \fBint sem_timedwait(sem_t *\fP\fIsem\fP\fB, const struct timespec *\fP\fIabs_timeout\fP\fB);\fP
  47 .fi
  48 .sp
  49 \fI\-pthread\fP とリンクする。
  50 .sp
  51 .in -4n
  52 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  53 .in
  54 .sp
  55 \fBsem_timedwait\fP(): _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
  56 .SH 説明
  57 \fBsem_wait\fP()  は \fIsem\fP が指すセマフォの値を 1 減らす (ロックする)。 セマフォの値が 0
  58 より大きい場合、減算が実行され、関数は直ちに復帰する。 セマフォの現在値が 0 の場合には、減算を実行できるようになる (つまり、セマフォの値が 0
  59 より大きな値になる) まで、もしくは シグナルハンドラによって呼び出しが中断されるまで、 関数呼び出しは停止 (block) する。
  60
  61 \fBsem_trywait\fP()  は \fBsem_wait\fP()  と同じだが、セマフォ値の減算をすぐに実行できなかった場合に、 停止 (block)
  62 するのではなくエラーで復帰する (\fIerrno\fP に \fBEAGAIN\fP がセットされる) 点が異なる。
  63
  64 \fBsem_timedwait\fP()  は \fBsem_wait\fP()  と同じだが、セマフォ値の減算をすぐに実行できなかった場合に
  65 関数呼び出しが停止する時間の上限を \fIabs_timeout\fP で指定する点が異なる。 \fIabs_timeout\fP
  66 引き数は、タイムアウト時刻を指定する構造体へのポインタである。 この構造体には、タイムアウト時刻を時刻紀元 (Epoch; 1970\-01\-01
  67 00:00:00 +0000 (UTC)) からの 経過時間 (秒＋ナノ秒) で指定する。 構造体は以下のように定義されている:
  68
  69 .nf
  70 .in +4n
  71 struct timespec {
  72     time_t tv_sec;      /* Seconds */
  73     long   tv_nsec;     /* Nanoseconds [0 .. 999999999] */
  74 };
  75 .in
  76 .fi
  77 .PP
  78 関数呼び出し時点ですでにタイムアウトに指定した時刻が過ぎており、 かつセマフォをすぐにロックできなかった場合は、 \fBsem_timedwait\fP()
  79 はタイムアウトエラー (\fIerrno\fP に \fBETIMEDOUT\fP がセットされる) で失敗する。
  80
  81 セマフォ操作がすぐに実行できるときは、 \fIabs_timeout\fP がどんな値であっても \fBsem_timedwait\fP()
  82 が失敗することは決してない。さらにいうと、この場合には \fIabs_timeout\fP の正当性の検査は行われない。
  83 .SH 返り値
  84 成功すると、これらの関数は 0 を返す。 エラーの場合、セマフォの値を変更せずに、\-1 を返し、 \fIerrno\fP にエラーを示す値をセットする。
  85 .SH エラー
  86 .TP
  87 \fBEINTR\fP
  88 呼び出しはシグナルハンドラにより中断された。 \fBsignal\fP(7)  参照。
  89 .TP
  90 \fBEINVAL\fP
  91 \fIsem\fP は有効なセマフォではない。
  92 .PP
  93 \fBsem_trywait\fP()  の場合には、上記に加えて以下のエラーも起こる。
  94 .TP
  95 \fBEAGAIN\fP
  96 停止 (block) せずにロック操作を完了できなかった (つまり、 セマフォの現在の値が 0 であった)。
  97 .PP
  98 \fBsem_timedwait\fP()  の場合、以下のエラーも起こる。
  99 .TP
 100 \fBEINVAL\fP
 101 \fIabs_timeout.tv_nsecs\fP の値が 0 未満、もしくは 1,000,000,000 以上である。
 102 .TP
 103 \fBETIMEDOUT\fP
 104 .\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition
 105 .\" was detected", but this does not occur on Linux(?).
 106 セマフォのロックに成功する前に時間切れとなった。
 107 .SH 準拠
 108 POSIX.1\-2001.
 109 .SH 注意
 110 .\" sem_wait() is always interrupted on most other implementations,
 111 .\" but on FreeBSD 5.4 SA_RESTART does cause restarting.
 112 シグナルハンドラは、 \fBsigaction\fP(2)  の \fBSA_RESTART\fP フラグを使用しているかどうかに関わらず、これらの関数の呼び出しが
 113 停止している場合、シグナルハンドラにより常に中断される。
 114 .SH 例
 115 .PP
 116 以下に示す (ちょっとした) プログラムは名前なしセマフォの操作を行う。 プログラムはコマンドライン引き数を 2 つ取る。 最初の引き数には、
 117 \fBSIGALRM\fP シグナルを生成するためのアラームタイマーの設定に使われる値を 秒単位で指定する。このシグナルハンドラは、 \fImain()\fP 内で
 118 \fBsem_timedwait\fP()  を使って待っているセマフォを、 \fBsem_post\fP(3)  を使って加算する。 2番目の引き数には、
 119 \fBsem_timedwait\fP()  に渡すタイムアウトまでの時間を秒単位で指定する。
 120
 121 .in +4n
 122 .nf
 123 $\fB ./a.out 2 3\fP
 124 About to call sem_timedwait()
 125 sem_post() from handler
 126 sem_timedwait() succeeded
 127 $\fB ./a.out 2 1\fP
 128 About to call sem_timedwait()
 129 sem_timedwait() timed out
 130 .fi
 131 .in
 132 .SS プログラムのソース
 133 \&
 134 .nf
 135 #include <unistd.h>
 136 #include <stdio.h>
 137 #include <stdlib.h>
 138 #include <semaphore.h>
 139 #include <time.h>
 140 #include <assert.h>
 141 #include <errno.h>
 142 #include <signal.h>
 143
 144 sem_t sem;
 145
 146 #define handle_error(msg) \e
 147     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 148
 149 static void
 150 handler(int sig)
 151 {
 152     write(STDOUT_FILENO, "sem_post() from handler\en", 24);
 153     if (sem_post(&sem) == \-1) {
 154         write(STDERR_FILENO, "sem_post() failed\en", 18);
 155         _exit(EXIT_FAILURE);
 156     }
 157 }
 158
 159 int
 160 main(int argc, char *argv[])
 161 {
 162     struct sigaction sa;
 163     struct timespec ts;
 164     int s;
 165
 166     if (argc != 3) {
 167         fprintf(stderr, "Usage: %s <alarm\-secs> <wait\-secs>\en",
 168                 argv[0]);
 169         exit(EXIT_FAILURE);
 170     }
 171
 172     if (sem_init(&sem, 0, 0) == \-1)
 173         handle_error("sem_init");
 174
 175     /* Establish SIGALRM handler; set alarm timer using argv[1] */
 176
 177     sa.sa_handler = handler;
 178     sigemptyset(&sa.sa_mask);
 179     sa.sa_flags = 0;
 180     if (sigaction(SIGALRM, &sa, NULL) == \-1)
 181         handle_error("sigaction");
 182
 183     alarm(atoi(argv[1]));
 184
 185     /* Calculate relative interval as current time plus
 186        number of seconds given argv[2] */
 187
 188     if (clock_gettime(CLOCK_REALTIME, &ts) == \-1)
 189         handle_error("clock_gettime");
 190
 191     ts.tv_sec += atoi(argv[2]);
 192
 193     printf("main() about to call sem_timedwait()\en");
 194     while ((s = sem_timedwait(&sem, &ts)) == \-1 && errno == EINTR)
 195         continue;       /* Restart if interrupted by handler */
 196
 197     /* Check what happened */
 198
 199     if (s == \-1) {
 200         if (errno == ETIMEDOUT)
 201             printf("sem_timedwait() timed out\en");
 202         else
 203             perror("sem_timedwait");
 204     } else
 205         printf("sem_timedwait() succeeded\en");
 206
 207     exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
 208 }
 209 .fi
 210 .SH 関連項目
 211 \fBclock_gettime\fP(2), \fBsem_getvalue\fP(3), \fBsem_post\fP(3), \fBsem_overview\fP(7),
 212 \fBtime\fP(7)
 213 .SH この文書について
 214 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 215 である。プロジェクトの説明とバグ報告に関する情報は
 216 http://www.kernel.org/doc/man\-pages/ に書かれている。