release/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 2014\-02\-26 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 .SS "マルチスレッディング (pthreads(7) 参照)"
 109 関数 \fBsem_wait\fP(), \fBsem_trywait\fP(), \fBsem_timedwait\fP() はスレッドセーフである。
 110 .SH 準拠
 111 POSIX.1\-2001.
 112 .SH 注意
 113 .\" sem_wait() is always interrupted on most other implementations,
 114 .\" but on FreeBSD 5.4 SA_RESTART does cause restarting.
 115 シグナルハンドラーは、 \fBsigaction\fP(2)  の \fBSA_RESTART\fP
 116 フラグを使用しているかどうかに関わらず、これらの関数の呼び出しが 停止している場合、シグナルハンドラーにより常に中断される。
 117 .SH 例
 118 .PP
 119 以下に示す (ちょっとした) プログラムは名前なしセマフォの操作を行う。 プログラムはコマンドライン引き数を 2 つ取る。 最初の引き数には、
 120 \fBSIGALRM\fP シグナルを生成するためのアラームタイマーの設定に使われる値を 秒単位で指定する。このシグナルハンドラーは、 \fImain()\fP
 121 内で \fBsem_timedwait\fP()  を使って待っているセマフォを、 \fBsem_post\fP(3)  を使って加算する。 2番目の引き数には、
 122 \fBsem_timedwait\fP()  に渡すタイムアウトまでの時間を秒単位で指定する。
 123
 124 .in +4n
 125 .nf
 126 $\fB ./a.out 2 3\fP
 127 About to call sem_timedwait()
 128 sem_post() from handler
 129 sem_timedwait() succeeded
 130 $\fB ./a.out 2 1\fP
 131 About to call sem_timedwait()
 132 sem_timedwait() timed out
 133 .fi
 134 .in
 135 .SS プログラムのソース
 136 \&
 137 .nf
 138 #include <unistd.h>
 139 #include <stdio.h>
 140 #include <stdlib.h>
 141 #include <semaphore.h>
 142 #include <time.h>
 143 #include <assert.h>
 144 #include <errno.h>
 145 #include <signal.h>
 146
 147 sem_t sem;
 148
 149 #define handle_error(msg) \e
 150     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 151
 152 static void
 153 handler(int sig)
 154 {
 155     write(STDOUT_FILENO, "sem_post() from handler\en", 24);
 156     if (sem_post(&sem) == \-1) {
 157         write(STDERR_FILENO, "sem_post() failed\en", 18);
 158         _exit(EXIT_FAILURE);
 159     }
 160 }
 161
 162 int
 163 main(int argc, char *argv[])
 164 {
 165     struct sigaction sa;
 166     struct timespec ts;
 167     int s;
 168
 169     if (argc != 3) {
 170         fprintf(stderr, "Usage: %s <alarm\-secs> <wait\-secs>\en",
 171                 argv[0]);
 172         exit(EXIT_FAILURE);
 173     }
 174
 175     if (sem_init(&sem, 0, 0) == \-1)
 176         handle_error("sem_init");
 177
 178     /* Establish SIGALRM handler; set alarm timer using argv[1] */
 179
 180     sa.sa_handler = handler;
 181     sigemptyset(&sa.sa_mask);
 182     sa.sa_flags = 0;
 183     if (sigaction(SIGALRM, &sa, NULL) == \-1)
 184         handle_error("sigaction");
 185
 186     alarm(atoi(argv[1]));
 187
 188     /* Calculate relative interval as current time plus
 189        number of seconds given argv[2] */
 190
 191     if (clock_gettime(CLOCK_REALTIME, &ts) == \-1)
 192         handle_error("clock_gettime");
 193
 194     ts.tv_sec += atoi(argv[2]);
 195
 196     printf("main() about to call sem_timedwait()\en");
 197     while ((s = sem_timedwait(&sem, &ts)) == \-1 && errno == EINTR)
 198         continue;       /* Restart if interrupted by handler */
 199
 200     /* Check what happened */
 201
 202     if (s == \-1) {
 203         if (errno == ETIMEDOUT)
 204             printf("sem_timedwait() timed out\en");
 205         else
 206             perror("sem_timedwait");
 207     } else
 208         printf("sem_timedwait() succeeded\en");
 209
 210     exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
 211 }
 212 .fi
 213 .SH 関連項目
 214 \fBclock_gettime\fP(2), \fBsem_getvalue\fP(3), \fBsem_post\fP(3), \fBsem_overview\fP(7),
 215 \fBtime\fP(7)
 216 .SH この文書について
 217 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 218 である。プロジェクトの説明とバグ報告に関する情報は
 219 http://www.kernel.org/doc/man\-pages/ に書かれている。