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 .\"*******************************************************************
  27 .\"
  28 .\" This file was generated with po4a. Translate the source file.
  29 .\"
  30 .\"*******************************************************************
  31 .TH SEM_WAIT 3 2012\-02\-12 Linux "Linux Programmer's Manual"
  32 .SH 名前
  33 sem_wait, sem_timedwait, sem_trywait \- セマフォをロックする
  34 .SH 書式
  35 .nf
  36 \fB#include <semaphore.h>\fP
  37 .sp
  38 \fBint sem_wait(sem_t *\fP\fIsem\fP\fB);\fP
  39 .sp
  40 \fBint sem_trywait(sem_t *\fP\fIsem\fP\fB);\fP
  41 .sp
  42 \fBint sem_timedwait(sem_t *\fP\fIsem\fP\fB, const struct timespec *\fP\fIabs_timeout\fP\fB);\fP
  43 .fi
  44 .sp
  45 \fI\-lrt\fP または \fI\-pthread\fP でリンクする。
  46 .sp
  47 .in -4n
  48 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  49 .in
  50 .sp
  51 \fBsem_timedwait\fP(): _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
  52 .SH 説明
  53 \fBsem_wait\fP()  は \fIsem\fP が指すセマフォの値を 1 減らす (ロックする)。 セマフォの値が 0
  54 より大きい場合、減算が実行され、関数は直ちに復帰する。 セマフォの現在値が 0 の場合には、減算を実行できるようになる (つまり、セマフォの値が 0
  55 より大きな値になる) まで、もしくは シグナルハンドラによって呼び出しが中断されるまで、 関数呼び出しは停止 (block) する。
  56
  57 \fBsem_trywait\fP()  は \fBsem_wait\fP()  と同じだが、セマフォ値の減算をすぐに実行できなかった場合に、 停止 (block)
  58 するのではなくエラーで復帰する (\fIerrno\fP に \fBEAGAIN\fP がセットされる) 点が異なる。
  59
  60 \fBsem_timedwait\fP()  は \fBsem_wait\fP()  と同じだが、セマフォ値の減算をすぐに実行できなかった場合に
  61 関数呼び出しが停止する時間の上限を \fIabs_timeout\fP で指定する点が異なる。 \fIabs_timeout\fP
  62 引き数は、タイムアウト時刻を指定する構造体へのポインタである。 この構造体には、タイムアウト時刻を時刻紀元 (Epoch; 1970\-01\-01
  63 00:00:00 +0000 (UTC)) からの 経過時間 (秒＋ナノ秒) で指定する。 構造体は以下のように定義されている:
  64
  65 .nf
  66 .in +4n
  67 struct timespec {
  68     time_t tv_sec;      /* Seconds */
  69     long   tv_nsec;     /* Nanoseconds [0 .. 999999999] */
  70 };
  71 .in
  72 .fi
  73 .PP
  74 関数呼び出し時点ですでにタイムアウトに指定した時刻が過ぎており、 かつセマフォをすぐにロックできなかった場合は、 \fBsem_timedwait\fP()
  75 はタイムアウトエラー (\fIerrno\fP に \fBETIMEDOUT\fP がセットされる) で失敗する。
  76
  77 セマフォ操作がすぐに実行できるときは、 \fIabs_timeout\fP がどんな値であっても \fBsem_timedwait\fP()
  78 が失敗することは決してない。さらにいうと、この場合には \fIabs_timeout\fP の正当性の検査は行われない。
  79 .SH 返り値
  80 成功すると、これらの関数は 0 を返す。 エラーの場合、セマフォの値を変更せずに、\-1 を返し、 \fIerrno\fP にエラーを示す値をセットする。
  81 .SH エラー
  82 .TP
  83 \fBEINTR\fP
  84 呼び出しはシグナルハンドラにより中断された。 \fBsignal\fP(7)  参照。
  85 .TP
  86 \fBEINVAL\fP
  87 \fIsem\fP は有効なセマフォではない。
  88 .PP
  89 \fBsem_trywait\fP()  の場合には、上記に加えて以下のエラーも起こる。
  90 .TP
  91 \fBEAGAIN\fP
  92 停止 (block) せずにロック操作を完了できなかった (つまり、 セマフォの現在の値が 0 であった)。
  93 .PP
  94 \fBsem_timedwait\fP()  の場合、以下のエラーも起こる。
  95 .TP
  96 \fBEINVAL\fP
  97 \fIabs_timeout.tv_nsecs\fP の値が 0 未満、もしくは 1,000,000,000 以上である。
  98 .TP
  99 \fBETIMEDOUT\fP
 100 .\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition
 101 .\" was detected", but this does not occur on Linux(?).
 102 セマフォのロックに成功する前に時間切れとなった。
 103 .SH 準拠
 104 POSIX.1\-2001.
 105 .SH 注意
 106 .\" sem_wait() is always interrupted on most other implementations,
 107 .\" but on FreeBSD 5.4 SA_RESTART does cause restarting.
 108 シグナルハンドラは、 \fBsigaction\fP(2)  の \fBSA_RESTART\fP フラグを使用しているかどうかに関わらず、これらの関数の呼び出しが
 109 停止している場合、シグナルハンドラにより常に中断される。
 110 .SH 例
 111 .PP
 112 以下に示す (ちょっとした) プログラムは名前なしセマフォの操作を行う。 プログラムはコマンドライン引き数を 2 つ取る。 最初の引き数には、
 113 \fBSIGALRM\fP シグナルを生成するためのアラームタイマーの設定に使われる値を 秒単位で指定する。このシグナルハンドラは、 \fImain()\fP 内で
 114 \fBsem_timedwait\fP()  を使って待っているセマフォを、 \fBsem_post\fP(3)  を使って加算する。 2番目の引き数には、
 115 \fBsem_timedwait\fP()  に渡すタイムアウトまでの時間を秒単位で指定する。
 116
 117 .in +4n
 118 .nf
 119 $\fB ./a.out 2 3\fP
 120 About to call sem_timedwait()
 121 sem_post() from handler
 122 sem_timedwait() succeeded
 123 $\fB ./a.out 2 1\fP
 124 About to call sem_timedwait()
 125 sem_timedwait() timed out
 126 .fi
 127 .in
 128 .SS プログラムのソース
 129 \&
 130 .nf
 131 #include <unistd.h>
 132 #include <stdio.h>
 133 #include <stdlib.h>
 134 #include <semaphore.h>
 135 #include <time.h>
 136 #include <assert.h>
 137 #include <errno.h>
 138 #include <signal.h>
 139
 140 sem_t sem;
 141
 142 #define handle_error(msg) \e
 143     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 144
 145 static void
 146 handler(int sig)
 147 {
 148     write(STDOUT_FILENO, "sem_post() from handler\en", 24);
 149     if (sem_post(&sem) == \-1) {
 150         write(STDERR_FILENO, "sem_post() failed\en", 18);
 151         _exit(EXIT_FAILURE);
 152     }
 153 }
 154
 155 int
 156 main(int argc, char *argv[])
 157 {
 158     struct sigaction sa;
 159     struct timespec ts;
 160     int s;
 161
 162     if (argc != 3) {
 163         fprintf(stderr, "Usage: %s <alarm\-secs> <wait\-secs>\en",
 164                 argv[0]);
 165         exit(EXIT_FAILURE);
 166     }
 167
 168     if (sem_init(&sem, 0, 0) == \-1)
 169         handle_error("sem_init");
 170
 171     /* Establish SIGALRM handler; set alarm timer using argv[1] */
 172
 173     sa.sa_handler = handler;
 174     sigemptyset(&sa.sa_mask);
 175     sa.sa_flags = 0;
 176     if (sigaction(SIGALRM, &sa, NULL) == \-1)
 177         handle_error("sigaction");
 178
 179     alarm(atoi(argv[1]));
 180
 181     /* Calculate relative interval as current time plus
 182        number of seconds given argv[2] */
 183
 184     if (clock_gettime(CLOCK_REALTIME, &ts) == \-1)
 185         handle_error("clock_gettime");
 186
 187     ts.tv_sec += atoi(argv[2]);
 188
 189     printf("main() about to call sem_timedwait()\en");
 190     while ((s = sem_timedwait(&sem, &ts)) == \-1 && errno == EINTR)
 191         continue;       /* Restart if interrupted by handler */
 192
 193     /* Check what happened */
 194
 195     if (s == \-1) {
 196         if (errno == ETIMEDOUT)
 197             printf("sem_timedwait() timed out\en");
 198         else
 199             perror("sem_timedwait");
 200     } else
 201         printf("sem_timedwait() succeeded\en");
 202
 203     exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
 204 }
 205 .fi
 206 .SH 関連項目
 207 \fBclock_gettime\fP(2), \fBsem_getvalue\fP(3), \fBsem_post\fP(3), \fBsem_overview\fP(7),
 208 \fBtime\fP(7)