release/man2/clock_nanosleep.2

   1 .\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
   2 .\" <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .\" Japanese Version Copyright (c) 2008  Akihiro MOTOKI
  25 .\"         all rights reserved.
  26 .\" Translated 2008-08-21, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.04
  27 .\"
  28 .TH CLOCK_NANOSLEEP 2 2010-12-03 "Linux" "Linux Programmer's Manual"
  29 .SH 名前
  30 clock_nanosleep \- 指定したクロックでの高精度な実行停止 (sleep)
  31 .SH 書式
  32 .B #include <time.h>
  33 .nf
  34 .sp
  35 .BI "int clock_nanosleep(clockid_t " clock_id ", int " flags ,
  36 .BI "                    const struct timespec *" request ,
  37 .BI "                    struct timespec *" remain );
  38 .fi
  39 .sp
  40 \fI\-lrt\fP でリンクする。
  41 .sp
  42 .ad l
  43 .in -4n
  44 glibc 向けの機能検査マクロの要件
  45 .RB ( feature_test_macros (7)
  46 参照):
  47 .in
  48 .sp
  49 .BR clock_nanosleep ():
  50 .RS 4
  51 _XOPEN_SOURCE\ >=\ 600 || _POSIX_C_SOURCE\ >=\ 200112L
  52 .RE
  53 .ad
  54 .SH 説明
  55 .BR clock_nanosleep ()
  56 を使うと、
  57 .BR nanosleep (2)
  58 同様、ナノ秒の精度で指定された期間だけ呼び出したスレッドの実行を
  59 停止することができる。
  60 .BR nanosleep (2)
  61 と違うのは、呼び出し側が停止期間をどのクロックに対して計測するのかを選択
  62 できる点と、停止期間を絶対値でも相対値でも指定できる点である。
  63
  64 このシステムコールに渡したり、このシステムコールが返したりする時間の値は
  65 .I timespec
  66 構造体を使って指定される。この構造体の定義は以下の通りである。
  67 .sp
  68 .in +4n
  69 .nf
  70 struct timespec {
  71     time_t tv_sec;        /* seconds */
  72     long   tv_nsec;       /* nanoseconds [0 .. 999999999] */
  73 };
  74 .fi
  75 .in
  76
  77 .I clock_id
  78 引き数で、停止期間をどのクロックに対して計測するかを指定する。
  79 この引き数には以下の値のいずれか一つを指定できる。
  80 .TP 17
  81 .BR CLOCK_REALTIME
  82 システム全体で使われる実時間クロック。
  83 このクロックは変更可能である。
  84 .TP
  85 .BR CLOCK_MONOTONIC
  86 過去のある時点からの時間を計測する、単調増加のクロック。
  87 起点となる時点はシステム起動後には変更されない。
  88 このクロックは変更することができない。
  89 .\" Linux では、このクロックは起動からの時間を計測する。
  90 .TP
  91 .BR CLOCK_PROCESS_CPUTIME_ID
  92 そのプロセスの全スレッドで消費される CPU 時間を計測するプロセス単位の
  93 クロック。このクロックは設定可能である。
  94 .\" There is some trickery between glibc and the kernel
  95 .\" to deal with the CLOCK_PROCESS_CPUTIME_ID case.
  96 .PP
  97 これらのクロックの詳細については
  98 .BR clock_getres (2)
  99 を参照。
 100
 101 .I flags
 102 が 0 の場合、
 103 .I request
 104 に指定された値は
 105 .I clock_id
 106 で指定されたクロックの現在の値からの相対的な期間と解釈される。
 107
 108 .I flags
 109 が
 110 .B TIMER_ABSTIME
 111 の場合、
 112 .I request
 113 は指定されたクロックで計測される絶対時刻と解釈される。
 114 .I request
 115 が指定されたクロックの現在の値以下の場合、
 116 .BR clock_nanosleep ()
 117 は、呼び出したスレッドの停止を行わず、すぐに返る。
 118
 119 .BR clock_nanosleep ()
 120 は、少なくとも
 121 .I request
 122 で指定された時間が経過するまで、呼び出したスレッドの実行を停止する。
 123 シグナルハンドラが呼び出されたり、そのプロセスを終了させるような
 124 シグナルが配送されたりした場合にも、スレッドの実行停止は終了する。
 125
 126 呼び出しがシグナルハンドラによって割り込まれた場合、
 127 .BR clock_nanosleep ()
 128 はエラー
 129 .B EINTR
 130 で失敗する。さらに、
 131 .I remain
 132 が NULL でなく、かつ
 133 .I flags
 134 が
 135 .B TIMER_ABSTIME
 136 でない場合には、
 137 .I remain
 138 に残りの停止時間が返される。
 139 この値を使って
 140 .BR clock_nanosleep ()
 141 を再度呼び出すことで、(相対的な期間の) 停止を完了することができる。
 142 .SH 返り値
 143 要求された期間の停止に成功すると、
 144 .BR clock_nanosleep ()
 145 は 0 を返す。
 146 シグナルハンドラで割り込まれたり、エラーが発生したりした場合、
 147 「エラー」の節のリストにある正のエラー番号のいずれか一つを返す。
 148 .SH エラー
 149 .TP
 150 .B EFAULT
 151 .I request
 152 や
 153 .I remain
 154 に無効なアドレスが指定された。
 155 .TP
 156 .B EINTR
 157 停止がシグナルハンドラにより割り込まれた。
 158 .TP
 159 .B EINVAL
 160 .I tv_nsec
 161 フィールドの値が 0 から 999999999 の範囲でないか、
 162 .I tv_sec
 163 の値が負であった。
 164 .TP
 165 .B EINVAL
 166 .I clock_id
 167 が無効であった
 168 .RB ( CLOCK_THREAD_CPUTIME_ID
 169 が
 170 .I clock_id
 171 として有効な値ではない)。
 172 .SH バージョン
 173 .BR clock_nanosleep ()
 174 システムコールは Linux 2.6 で初めて登場した。
 175 glibc ではバージョン 2.1 以降でサポートされている。
 176 .SH 準拠
 177 POSIX.1-2001.
 178 .SH 注意
 179 .I request
 180 で指定された停止期間が、時間の計測に使用されるクロック
 181 .RB ( time (7)
 182 参照) の精度の倍数ちょうどでない場合、停止期間は一番近い次の倍数に
 183 切り上げられる。さらに、停止が完了した後に、CPU が呼び出したスレッドを
 184 もう一度実行できるようになるまでには、遅延が入る可能性がある。
 185
 186 絶対値指定のタイマを使うのは、
 187 .BR nanosleep (2)
 188 に書かれている類のタイマのずれの問題を防止するのに役立つ
 189 (この種の問題は、シグナルに割り込まれた際に相対指定の停止を
 190 繰り返し再開しようとするプログラムでは、かえって悪化する)。
 191 これらの問題を回避して相対指定の停止を実行するには、
 192 希望するクロックで
 193 .BR clock_gettime (2)
 194 を呼び出し、その返り値の時刻値に希望する期間を加算してから、
 195 .B TIMER_ABSTIME
 196 フラグを指定して
 197 .BR clock_nanosleep ()
 198 を呼び出す。
 199
 200 .BR sigaction (2)
 201 で
 202 .BR SA_RESTART
 203 フラグが指定されているかに関わらず、
 204 シグナルハンドラにより割り込まれた後に
 205 .BR clock_nanosleep ()
 206 が再開されることは決してない。
 207
 208 .I flags
 209 が
 210 .B TIMER_ABSTIME
 211 の場合、
 212 .I remain
 213 引き数は使用されず、不要である
 214 (絶対値での停止では、同じ
 215 .I request
 216 引き数を使って再度呼び出すことができる)。
 217
 218 POSIX.1 の規定では、
 219 .BR clock_nanosleep ()
 220 はシグナルの処理方法やシグナルマスクに影響を与えない、とされている。
 221
 222 POSIX.1 の規定では、
 223 .BR clock_settime (2)
 224 で
 225 .B CLOCK_REALTIME
 226 クロックの値を変更した後は、絶対値指定の
 227 .BR clock_nanosleep ()
 228 で停止しているスレッドを起動させる時刻の判定は、
 229 新しいクロック値を使って行われる、とされている。
 230 新しいクロック値において停止期間の終了時刻が過去になってしまった場合には、
 231 .BR clock_nanosleep ()
 232 はすぐに返ることになる。
 233
 234 POSIX.1 の規定では、
 235 .BR clock_settime (2)
 236 で
 237 .B CLOCK_REALTIME
 238 クロックの値を変更しても、相対値指定の
 239 .BR clock_nanosleep ()
 240 で停止しているスレッドには影響を与えない、とされている。
 241 .SH 関連項目
 242 .BR clock_getres (2),
 243 .BR nanosleep (2),
 244 .BR timer_create (2),
 245 .BR sleep (3),
 246 .BR usleep (3),
 247 .BR time (7)