release/man2/nanosleep.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) Markus Kuhn, 1996
   4 .\" and Copyright (C) Linux Foundation, 2008, written by Michael Kerrisk
   5 .\"     <mtk.manpages@gmail.com>
   6 .\"
   7 .\" This is free documentation; you can redistribute it and/or
   8 .\" modify it under the terms of the GNU General Public License as
   9 .\" published by the Free Software Foundation; either version 2 of
  10 .\" the License, or (at your option) any later version.
  11 .\"
  12 .\" The GNU General Public License's references to "object code"
  13 .\" and "executables" are to be interpreted as the output of any
  14 .\" document formatting or typesetting system, including
  15 .\" intermediate and printed output.
  16 .\"
  17 .\" This manual is distributed in the hope that it will be useful,
  18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 .\" GNU General Public License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public
  23 .\" License along with this manual; if not, write to the Free
  24 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  25 .\" USA.
  26 .\"
  27 .\" 1996-04-10  Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
  28 .\"             First version written
  29 .\" Modified, 2004-10-24, aeb
  30 .\" 2008-06-24, mtk
  31 .\"     Minor rewrites of some parts.
  32 .\"     NOTES: describe case where clock_nanosleep() can be preferable.
  33 .\"     NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP
  34 .\"     Replace crufty discussion of HZ with a pointer to time(7).
  35 .\"
  36 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  37 .\"         all rights reserved.
  38 .\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  39 .\" Updated 1999-02-27, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  40 .\" Updated 2003-09-15, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  41 .\" Updated 2005-02-10, Akihiro MOTOKI
  42 .\" Updated 2006-07-23, Akihiro MOTOKI, LDP v2.36
  43 .\" Updated 2006-08-13, Akihiro MOTOKI, LDP v2.39
  44 .\" Updated 2008-08-08, Akihiro MOTOKI, LDP v3.05
  45 .\"
  46 .\"WORD:        puase                   停止
  47 .\"WORD:        sleep                   停止
  48 .\"WORD:        signal                  シグナル
  49 .\"WORD:        NULL                    NULL
  50 .\"WORD:        block                   禁止(block)
  51 .\"WORD:        kernel                  カーネル
  52 .\"WORD:        real-time               リアル・タイム
  53 .\"WORD:        schedule                スケジュール
  54 .\"WORD:        busy wait               ビシー・ウェイト
  55 .\"
  56 .TH NANOSLEEP 2 2009-01-19 "Linux" "Linux Programmer's Manual"
  57 .SH 名前
  58 nanosleep \- 高精度なスリープ
  59 .SH 書式
  60 .B #include <time.h>
  61 .sp
  62 .BI "int nanosleep(const struct timespec *" req ", struct timespec *" rem );
  63 .sp
  64 .in -4n
  65 glibc 向けの機能検査マクロの要件
  66 .RB ( feature_test_macros (7)
  67 参照):
  68 .in
  69 .sp
  70 .BR nanosleep ():
  71 _POSIX_C_SOURCE\ >=\ 199309L
  72 .SH 説明
  73 .BR nanosleep ()
  74 は、少なくとも
  75 .I *req
  76 で指定された時間の間、プログラムの実行を遅延させる。
  77 .BR nanosleep ()
  78 は、呼び出したスレッドの実行を、
  79 少なくとも
  80 .I *req
  81 で指定された時間の間、もしくは呼び出したスレッドでハンドラの起動の
  82 きっかけとなるシグナル、またはプロセスを終了させるシグナルの配送が
  83 行われるまで一時停止する。
  84
  85 呼び出しがシグナルハンドラにより割り込まれた場合、
  86 .BR nanosleep
  87 は \-1 を返し、
  88 .I errno
  89 に
  90 .B EINTR
  91 を設定し、
  92 .I rem
  93 が NULL でなければ
  94 残りの時間を
  95 .I rem
  96 が指す構造体に格納する。
  97 .I *rem
  98 の値を使うと、
  99 .BR nanosleep ()
 100 をもう一度呼び出して、指定した時間の停止を
 101 完了させることができる (但し、「注意」の節を参照のこと)。
 102
 103 ナノ秒刻みの時間間隔を指定するのに
 104 .I timespec
 105 構造体が使用される。この構造体は次のように定義されている。
 106 .sp
 107 .in +4n
 108 .nf
 109     time_t tv_sec;        /* 秒 */
 110     long   tv_nsec;       /* ナノ秒 */
 111 };
 112 .fi
 113 .in
 114 .PP
 115 ナノ秒のフィールドの値は 0 から 999999999 の範囲になければならない。
 116
 117 .BR sleep  (3)
 118 や
 119 .BR usleep (3)
 120 に比べると
 121 .BR nanosleep ()
 122 には以下のような利点がある:
 123 停止期間の指定に関して高い時間分解能が提供されている。
 124 シグナルと互いに影響を及ぼすことがないと
 125 POSIX.1 で明示的に規定されている。
 126 シグナルハンドラによって割り込まれた際に、停止を再開するのが
 127 より簡単にできる。
 128 .SH 返り値
 129 要求された期間の停止に成功した場合、
 130 .BR nanosleep ()
 131 は 0 を返す。呼び出しがシグナルハンドラにより割り込まれたり、
 132 エラーが発生した場合は、\-1 を返し、
 133 .I errno
 134 にエラー内容を示す値を設定する。
 135 .SH エラー
 136 .TP
 137 .B EFAULT
 138 ユーザ空間からの情報のコピーで問題があった。
 139 .TP
 140 .B EINTR
 141 そのスレッドに配送されたシグナルにより停止が中断された。
 142 スレッドが簡単に
 143 .BR nanosleep ()
 144 を再び呼び出して停止を続けることができるように、
 145 残りの停止時間が \fI*rem\fP に格納される。
 146 .TP
 147 .B EINVAL
 148 .I tv_nsec
 149 フィールドの値が 0 から 999999999 までの範囲になかったか、
 150 .I tv_sec
 151 が負であった。
 152 .SH 準拠
 153 POSIX.1-2001.
 154 .SH 注意
 155 .I req
 156 で指定された期間が、内部で使用されるクロックの粒度の倍数になっていない
 157 場合、期間は一番近い倍数に切り上げられる。
 158 また、停止が完了した後、CPU が呼び出し元のスレッドを再び実行できるように
 159 なるまでには遅延が入る。
 160
 161 シグナルによる割り込み後に繰り返し再開された場合、
 162 .BR nanosleep ()
 163 の停止が相対的な期間であることは問題となることがある。
 164 これは、呼び出しの割り込みから再開までの間の時間が原因で
 165 停止が最終的に完了した際に時間にずれが発生するからである。
 166 この問題は、絶対時刻が指定できる
 167 .BR clock_nanosleep (2)
 168 を使うことで回避できる。
 169
 170 POSIX.1 は、
 171 .BR nanosleep ()
 172 は
 173 .B CLOCK_REALTIME
 174 に対して時刻を計測するべきだと規定している。
 175 しかしながら、Linux は
 176 .B CLOCK_MONOTONIC
 177 クロックを用いて時刻を計測している。
 178 .\" See also http://thread.gmane.org/gmane.linux.kernel/696854/
 179 .\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME?
 180 .\" Date: 2008-06-22 07:35:41 GMT
 181 このことはおそらく問題にならないだろう。
 182 なぜなら、POSIX.1 の
 183 .BR clock_settime (2)
 184 の仕様には、
 185 .B CLOCK_REALTIME
 186 の不連続な変化は
 187 .BR nanosleep ()
 188 に影響すべきではない、と書かれているからである。
 189 .RS
 190 .PP
 191 .BR clock_settime (2)
 192 経由で
 193 .B CLOCK_REALTIME
 194 クロックの値を設定しても、
 195 .BR nanosleep ()
 196 関数などの
 197 .B CLOCK_REALTIME
 198 に基づくサービスにより相対的な期間だけ実行を停止するスレッドには影響はない。
 199 結果として、クロック値が更新前か後かに関わらず、要求された相対的な時間が
 200 経過すると満了することになる。
 201 .RE
 202 .SS 以前の動作
 203 (例えば、時間が重要な意味を持つハードウェアを制御する場合など)
 204 より正確な停止を必要とするアプリケーションに対応するために、
 205 .BR nanosleep ()
 206 は、マイクロ秒精度のビジー・ウェイトを利用することで、
 207 2\ ms 以下の停止を行うことができた。
 208 但し、この機能を利用するには、呼び出し元のスレッドが
 209 .B SCHED_FIFO
 210 や
 211 .B SCHED_RR
 212 といったリアルタイム・ポリシーの元でスケジューリングされている
 213 必要があった。
 214 この特別な拡張はカーネル 2.5.39 で削除された。したがって、
 215 現在の 2.4 系列のカーネルにはこの機能が存在するが、
 216 2.6系列のカーネルにはない。
 217 .SH バグ
 218 Linux 2.4 では、
 219 .BR nanosleep ()
 220 が
 221 .RB ( SIGTSTP
 222 などの) シグナルにより停止された場合、
 223 .BR nanosleep ()
 224 の呼び出しは
 225 .B SIGCONT
 226 シグナルによるスレッドの再開後に
 227 .B EINTR
 228 エラーで失敗する。
 229 システムコールがこの後で再スタートされた場合、
 230 スレッドが停止状態にある間に経過した時間は
 231 停止期間としてカウント「されない」。
 232 .SH 関連項目
 233 .BR clock_nanosleep (2),
 234 .BR sched_setscheduler (2),
 235 .BR timer_create (2),
 236 .BR sleep (3),
 237 .BR usleep (3),
 238 .BR time (7)