.\" t
.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 2006 Akihiro MOTOKI all rights reserved.
.\" Translated 2006-04-18, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\"
.TH SEM_WAIT 3 2014\-02\-26 Linux "Linux Programmer's Manual"
.SH 名前
sem_wait, sem_timedwait, sem_trywait \- セマフォをロックする
.SH 書式
.nf
\fB#include <semaphore.h>\fP
.sp
\fBint sem_wait(sem_t *\fP\fIsem\fP\fB);\fP
.sp
\fBint sem_trywait(sem_t *\fP\fIsem\fP\fB);\fP
.sp
\fBint sem_timedwait(sem_t *\fP\fIsem\fP\fB, const struct timespec *\fP\fIabs_timeout\fP\fB);\fP
.fi
.sp
\fI\-pthread\fP とリンクする。
.sp
.in -4n
glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
.in
.sp
\fBsem_timedwait\fP(): _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
.SH 説明
\fBsem_wait\fP()  は \fIsem\fP が指すセマフォの値を 1 減らす (ロックする)。 セマフォの値が 0
より大きい場合、減算が実行され、関数は直ちに復帰する。 セマフォの現在値が 0 の場合には、減算を実行できるようになる (つまり、セマフォの値が 0
より大きな値になる) まで、もしくは シグナルハンドラーによって呼び出しが中断されるまで、 関数呼び出しは停止 (block) する。

\fBsem_trywait\fP()  は \fBsem_wait\fP()  と同じだが、セマフォ値の減算をすぐに実行できなかった場合に、 停止 (block)
するのではなくエラーで復帰する (\fIerrno\fP に \fBEAGAIN\fP がセットされる) 点が異なる。

\fBsem_timedwait\fP()  は \fBsem_wait\fP()  と同じだが、セマフォ値の減算をすぐに実行できなかった場合に
関数呼び出しが停止する時間の上限を \fIabs_timeout\fP で指定する点が異なる。 \fIabs_timeout\fP
引き数は、タイムアウト時刻を指定する構造体へのポインターである。 この構造体には、タイムアウト時刻を時刻紀元 (Epoch; 1970\-01\-01
00:00:00 +0000 (UTC)) からの 経過時間 (秒＋ナノ秒) で指定する。 構造体は以下のように定義されている:

.nf
.in +4n
struct timespec {
    time_t tv_sec;      /* Seconds */
    long   tv_nsec;     /* Nanoseconds [0 .. 999999999] */
};
.in
.fi
.PP
関数呼び出し時点ですでにタイムアウトに指定した時刻が過ぎており、 かつセマフォをすぐにロックできなかった場合は、 \fBsem_timedwait\fP()
はタイムアウトエラー (\fIerrno\fP に \fBETIMEDOUT\fP がセットされる) で失敗する。

セマフォ操作がすぐに実行できるときは、 \fIabs_timeout\fP がどんな値であっても \fBsem_timedwait\fP()
が失敗することは決してない。さらにいうと、この場合には \fIabs_timeout\fP の正当性の検査は行われない。
.SH 返り値
成功すると、これらの関数は 0 を返す。 エラーの場合、セマフォの値を変更せずに、\-1 を返し、 \fIerrno\fP にエラーを示す値をセットする。
.SH エラー
.TP 
\fBEINTR\fP
呼び出しはシグナルハンドラーにより中断された。 \fBsignal\fP(7)  参照。
.TP 
\fBEINVAL\fP
\fIsem\fP は有効なセマフォではない。
.PP
\fBsem_trywait\fP()  の場合には、上記に加えて以下のエラーも起こる。
.TP 
\fBEAGAIN\fP
停止 (block) せずにロック操作を完了できなかった (つまり、 セマフォの現在の値が 0 であった)。
.PP
\fBsem_timedwait\fP()  の場合、以下のエラーも起こる。
.TP 
\fBEINVAL\fP
\fIabs_timeout.tv_nsecs\fP の値が 0 未満、もしくは 1,000,000,000 以上である。
.TP 
\fBETIMEDOUT\fP
.\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition
.\" was detected", but this does not occur on Linux(?).
セマフォのロックに成功する前に時間切れとなった。
.SH 属性
.SS "マルチスレッディング (pthreads(7) 参照)"
関数 \fBsem_wait\fP(), \fBsem_trywait\fP(), \fBsem_timedwait\fP() はスレッドセーフである。
.SH 準拠
POSIX.1\-2001.
.SH 注意
.\" sem_wait() is always interrupted on most other implementations,
.\" but on FreeBSD 5.4 SA_RESTART does cause restarting.
シグナルハンドラーは、 \fBsigaction\fP(2)  の \fBSA_RESTART\fP
フラグを使用しているかどうかに関わらず、これらの関数の呼び出しが 停止している場合、シグナルハンドラーにより常に中断される。
.SH 例
.PP
以下に示す (ちょっとした) プログラムは名前なしセマフォの操作を行う。 プログラムはコマンドライン引き数を 2 つ取る。 最初の引き数には、
\fBSIGALRM\fP シグナルを生成するためのアラームタイマーの設定に使われる値を 秒単位で指定する。このシグナルハンドラーは、 \fImain()\fP
内で \fBsem_timedwait\fP()  を使って待っているセマフォを、 \fBsem_post\fP(3)  を使って加算する。 2番目の引き数には、
\fBsem_timedwait\fP()  に渡すタイムアウトまでの時間を秒単位で指定する。

.in +4n
.nf
$\fB ./a.out 2 3\fP
About to call sem_timedwait()
sem_post() from handler
sem_timedwait() succeeded
$\fB ./a.out 2 1\fP
About to call sem_timedwait()
sem_timedwait() timed out
.fi
.in
.SS プログラムのソース
\&
.nf
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <semaphore.h>
#include <time.h>
#include <assert.h>
#include <errno.h>
#include <signal.h>

sem_t sem;

#define handle_error(msg) \e
    do { perror(msg); exit(EXIT_FAILURE); } while (0)

static void
handler(int sig)
{
    write(STDOUT_FILENO, "sem_post() from handler\en", 24);
    if (sem_post(&sem) == \-1) {
        write(STDERR_FILENO, "sem_post() failed\en", 18);
        _exit(EXIT_FAILURE);
    }
}

int
main(int argc, char *argv[])
{
    struct sigaction sa;
    struct timespec ts;
    int s;

    if (argc != 3) {
        fprintf(stderr, "Usage: %s <alarm\-secs> <wait\-secs>\en",
                argv[0]);
        exit(EXIT_FAILURE);
    }

    if (sem_init(&sem, 0, 0) == \-1)
        handle_error("sem_init");

    /* Establish SIGALRM handler; set alarm timer using argv[1] */

    sa.sa_handler = handler;
    sigemptyset(&sa.sa_mask);
    sa.sa_flags = 0;
    if (sigaction(SIGALRM, &sa, NULL) == \-1)
        handle_error("sigaction");

    alarm(atoi(argv[1]));

    /* Calculate relative interval as current time plus
       number of seconds given argv[2] */

    if (clock_gettime(CLOCK_REALTIME, &ts) == \-1)
        handle_error("clock_gettime");

    ts.tv_sec += atoi(argv[2]);

    printf("main() about to call sem_timedwait()\en");
    while ((s = sem_timedwait(&sem, &ts)) == \-1 && errno == EINTR)
        continue;       /* Restart if interrupted by handler */

    /* Check what happened */

    if (s == \-1) {
        if (errno == ETIMEDOUT)
            printf("sem_timedwait() timed out\en");
        else
            perror("sem_timedwait");
    } else
        printf("sem_timedwait() succeeded\en");

    exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
}
.fi
.SH 関連項目
\fBclock_gettime\fP(2), \fBsem_getvalue\fP(3), \fBsem_post\fP(3), \fBsem_overview\fP(7),
\fBtime\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。