draft/man2/getitimer.2

   1 .\" Copyright 7/93 by Darren Senn <sinster@scintilla.santa-clara.ca.us>
   2 .\" Based on a similar page Copyright 1992 by Rick Faith
   3 .\" May be freely distributed
   4 .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
   5 .\" 2005-04-06 mtk, Matthias Lang <matthias@corelatus.se>
   6 .\"     Noted MAX_SEC_IN_JIFFIES ceiling
   7 .\"
   8 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
   9 .\"         all rights reserved.
  10 .\" Translated 1997-02-22, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  11 .\" Updated 2005-04-23, Kentaro Shirakata <argrath@ub32.org>
  12 .\" Updated 2005-09-11, Kentaro Shirakata <argrath@ub32.org>
  13 .\" Updated 2006-07-23, Kentaro Shirakata <argrath@ub32.org>
  14 .\" Updated 2007-10-14, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  15 .\" Updated 2009-04-13, Akihiro MOTOKI, LDP v3.20
  16 .\"
  17 .\" WORD:       timer   タイマー
  18 .\" WORD:       jiffies jiffy
  19 .\"
  20 .TH GETITIMER 2 2009-03-15 "Linux" "Linux Programmer's Manual"
  21 .SH 名前
  22 getitimer, setitimer \- インターバル・タイマーの値を取得または設定する
  23 .SH 書式
  24 .nf
  25 .B #include <sys/time.h>
  26 .sp
  27 .BI "int getitimer(int " which ", struct itimerval *" curr_value );
  28 .br
  29 .BI "int setitimer(int " which ", const struct itimerval *" new_value ,
  30 .BI "              struct itimerval *" old_value );
  31 .fi
  32 .SH 説明
  33 .\"O The system provides each process with three interval timers, each decrementing
  34 .\"O in a distinct time domain.
  35 .\"O When any timer expires, a signal is sent to the
  36 .\"O process, and the timer (potentially) restarts.
  37 システムは 1 個のプロセスにつき 3 個のインターバル・タイマーを提供する。
  38 それぞれのタイマーは別々の時間領域で減少する。
  39 どのタイマーも満了するとプロセスにシグナルが送られ、
  40 タイマーは (設定によっては) 再び開始される。
  41 .TP 1.5i
  42 .\"O .B ITIMER_REAL
  43 .\"O decrements in real time, and delivers
  44 .\"O .B SIGALRM
  45 .\"O upon expiration.
  46 .B ITIMER_REAL
  47 実時間 (real time) で減少し、満了すると
  48 .B SIGALRM
  49 が送られる。
  50 .TP
  51 .\"O .B ITIMER_VIRTUAL
  52 .\"O decrements only when the process is executing, and delivers
  53 .\"O .B SIGVTALRM
  54 .\"O upon expiration.
  55 .B ITIMER_VIRTUAL
  56 プロセスが実行されている間のみ減少し、満了すると
  57 .B SIGVTALRM
  58 が送られる。
  59 .TP
  60 .\"O .B ITIMER_PROF
  61 .\"O decrements both when the process executes and when the system is executing
  62 .\"O on behalf of the process.
  63 .\"O Coupled with
  64 .\"O .BR ITIMER_VIRTUAL ,
  65 .\"O this timer is usually used to profile the time spent by the
  66 .\"O application in user and kernel space.
  67 .\"O .B SIGPROF
  68 .\"O is delivered upon expiration.
  69 .B ITIMER_PROF
  70 プロセスが実行されていて、
  71 かつシステムがそのプロセスのために処理を行なっている間に減少する。
  72 多くの場合、このタイマーは
  73 .B ITIMER_VIRTUAL
  74 と組み合わされて、アプリケーションがカーネル空間とユーザー空間で
  75 どれだけの時間を過ごしたかをプロファイルするのに使用される。
  76 満了すると
  77 .B SIGPROF
  78 が送られる。
  79 .LP
  80 .\"O Timer values are defined by the following structures:
  81 タイマーの値は以下の構造体によって定義される:
  82 .PD 0
  83 .in +4n
  84 .nf
  85
  86 struct itimerval {
  87     struct timeval it_interval; /* next value */
  88     struct timeval it_value;    /* current value */
  89 };
  90
  91 struct timeval {
  92     long tv_sec;                /* seconds */
  93     long tv_usec;               /* microseconds */
  94 };
  95 .fi
  96 .in
  97 .PD
  98 .LP
  99 .\"O The function
 100 .\"O .BR getitimer ()
 101 .\"O fills the structure pointed to by
 102 .\"O .I curr_value
 103 .\"O with the current setting for the timer specified by
 104 .\"O .I which
 105 .\"O (one of
 106 .\"O .BR ITIMER_REAL ,
 107 .\"O .BR ITIMER_VIRTUAL ,
 108 .\"O or
 109 .\"O .BR ITIMER_PROF ).
 110 .BR getitimer ()
 111 関数は、
 112 .I which
 113 で指定されたタイマー
 114 .RB ( ITIMER_REAL ,
 115 .BR ITIMER_VIRTUAL ,
 116 .B ITIMER_PROF
 117 のどれか) の現在の設定を、
 118 .I curr_value
 119 で指定された構造体に格納する。
 120 .\"O The element
 121 .\"O .I it_value
 122 .\"O is set to the amount of time remaining on the timer, or zero if the timer
 123 .\"O is disabled.
 124 .\"O Similarly,
 125 .\"O .I it_interval
 126 .\"O is set to the reset value.
 127 .I it_value
 128 要素にはタイマーの残り時間が設定される。タイマーがオフの場合は
 129 ゼロが設定される。同様に
 130 .I it_interval
 131 には初期値が設定される。
 132
 133 .\"O The function
 134 .\"O .BR setitimer ()
 135 .\"O sets the specified timer to the value in
 136 .\"O .IR new_value .
 137 .BR setitimer ()
 138 関数は指定されたタイマーに
 139 .I new_value
 140 の値を設定する。
 141 .\"O If
 142 .\"O .I old_value
 143 .\"O is non-NULL, the old value of the timer is stored there.
 144 .I old_value
 145 が NULL 以外の場合、タイマーの古い値が
 146 .I old_value
 147 に格納される。
 148 .LP
 149 .\"O Timers decrement from
 150 .\"O .I it_value
 151 .\"O to zero, generate a signal, and reset to
 152 .\"O .IR it_interval .
 153 タイマーは
 154 .I it_value
 155 からゼロへ向けて減っていき、シグナルを生成し、
 156 .I it_interval
 157 に初期化される。
 158 .\"O A timer which is set to zero
 159 .\"O .RI ( it_value
 160 .\"O is zero or the timer expires and
 161 .\"O .I it_interval
 162 .\"O is zero) stops.
 163 タイマーがゼロに設定された場合
 164 .RI ( it_value
 165 がゼロか、タイマーが満了した時に
 166 .I it_interval
 167 がゼロの場合) は停止する。
 168 .LP
 169 .\"O Both
 170 .\"O .I tv_sec
 171 .\"O and
 172 .\"O .I tv_usec
 173 .\"O are significant in determining the duration of a timer.
 174 タイマーの期間は
 175 .I tv_sec
 176 と
 177 .I tv_usec
 178 の両方により決定される。
 179 .LP
 180 .\"O Timers will never expire before the requested time,
 181 .\"O but may expire some (short) time afterward, which depends
 182 .\"O on the system timer resolution and on the system load; see
 183 .\"O .BR time (7).
 184 .\"O (But see BUGS below.)
 185 .\"O Upon expiration, a signal will be generated and the timer reset.
 186 .\"O If the timer expires while the process is active (always true for
 187 .\"O .BR ITIMER_VIRTUAL )
 188 .\"O the signal will be delivered immediately when generated.
 189 .\"O Otherwise the
 190 .\"O delivery will be offset by a small time dependent on the system loading.
 191 要求した時間がくる前にタイマーが満了することはないが、
 192 逆にある (短い) 時間だけ満了が遅れることはある。
 193 どれだけ遅れるかはシステムの時間分解能とシステムの負荷に依存する
 194 .RB ( time (7)
 195 参照; 但し、バグの項も参照のこと)。
 196 タイマーが満了するとシグナルが生成され、タイマーは初期化される。
 197 プロセスがアクティブな時
 198 .RB ( ITIMER_VIRTUAL
 199 の場合には常にそうである) にタイマーが満了した場合、生成されたシグナルは
 200 すぐに配送される。それ以外の場合は、システムの負荷により少しの時間だけ
 201 遅れて配送される。
 202 .SH 返り値
 203 .\"O On success, zero is returned.
 204 .\"O On error, \-1 is returned, and
 205 .\"O .I errno
 206 .\"O is set appropriately.
 207 成功した場合はゼロが返る。エラーの場合は \-1 が返り、
 208 .I errno
 209 が適切に設定される。
 210 .SH エラー
 211 .TP
 212 .B EFAULT
 213 .\"O .IR new_value ,
 214 .\"O .IR old_value ,
 215 .\"O or
 216 .\"O .I curr_value
 217 .\"O is not valid a pointer.
 218 .IR new_value ,
 219 .IR old_value ,
 220 .I curr_value
 221 が有効なポインターでない。
 222 .TP
 223 .B EINVAL
 224 .\"O .I which
 225 .\"O is not one of
 226 .\"O .BR ITIMER_REAL ,
 227 .\"O .BR ITIMER_VIRTUAL ,
 228 .\"O or
 229 .\"O .BR ITIMER_PROF ;
 230 .\"O or (since Linux 2.6.22) one of the
 231 .\"O .I tv_usec
 232 .\"O fields in the structure pointed to by
 233 .\"O .I new_value
 234 .\"O contains a value outside the range 0 to 999999.
 235 .I which
 236 が
 237 .BR ITIMER_REAL ,
 238 .BR ITIMER_VIRTUAL ,
 239 .B ITIMER_PROF
 240 のどれでもない。
 241 または (Linux 2.6.22 以降で)
 242 .I new_value
 243 で指定された構造体の
 244 .I tv_usec
 245 フィールドの一つが 0 以上 999999 以下の範囲に入らない値である。
 246 .\"O .SH "CONFORMING TO"
 247 .SH 準拠
 248 .\"O POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
 249 POSIX.1-2001, SVr4, 4.4BSD (このコールは 4.2BSD で始めて現われた).
 250 .\"O POSIX.1-2008 marks
 251 .\"O .BR getitimer ()
 252 .\"O and
 253 .\"O .BR setitimer ()
 254 .\"O obsolete, recommending the use of the POSIX timers API
 255 .\"O .RB ( timer_gettime (2),
 256 .\"O .BR timer_settime (2),
 257 .\"O etc.) instead.
 258 POSIX.1-2008 では、
 259 .BR getitimer ()
 260 と
 261 .BR setitimer ()
 262 は廃止予定とされており、
 263 代わりに POSIX タイマー API
 264 .RB ( timer_gettime (2),
 265 .BR timer_settime (2)
 266 など) を使うことが推奨されている。
 267 .\"O .SH NOTES
 268 .SH 注意
 269 .\"O A child created via
 270 .\"O .BR fork (2)
 271 .\"O does not inherit its parent's interval timers.
 272 .\"O Interval timers are preserved across an
 273 .\"O .BR execve (2).
 274 .BR fork (2)
 275 で作成された子プロセスは、
 276 親プロセスのインターバル・タイマーを継承しない。
 277 .BR execve (2)
 278 の前後ではインターバル・タイマーは保存される。
 279
 280 .\"O POSIX.1 leaves the
 281 .\"O interaction between
 282 .\"O .BR setitimer ()
 283 .\"O and the three interfaces
 284 .\"O .BR alarm (2),
 285 .\"O .BR sleep (3),
 286 .\"O and
 287 .\"O .BR usleep (3)
 288 .\"O unspecified.
 289 POSIX.1 では、
 290 .BR setitimer ()
 291 と、
 292 .BR alarm (2),
 293 .BR sleep (3),
 294 .BR usleep (3)
 295 という 3 つのインタフェースとの相互の影響については規定していない。
 296 .\"O .SH BUGS
 297 .SH バグ
 298 .\"O The generation and delivery of a signal are distinct, and
 299 .\"O only one instance of each of the signals listed above may be pending
 300 .\"O for a process.
 301 .\"O Under very heavy loading, an
 302 .\"O .B ITIMER_REAL
 303 .\"O timer may expire before the signal from a previous expiration
 304 .\"O has been delivered.
 305 .\"O The second signal in such an event will be lost.
 306 シグナルの生成と配送は別個のものであり、
 307 前述のシグナルのそれぞれについて一つだけがプロセスのために
 308 待機する。
 309 非常に重い負荷の下では、
 310 .B ITIMER_REAL
 311 タイマーでは、時間切れにより生成された一つ前のシグナルが配送される前に、
 312 次の時間切れが起こる場合がある。
 313 そのような場合、 2 個めのイベントに対するシグナルは失われてしまう。
 314
 315 .\"O On Linux kernels before 2.6.16, timer values are represented in jiffies.
 316 バージョン 2.6.16 より前の Linux カーネルでは、
 317 タイマーの値は jiffy で表現される。
 318 .\"O If a request is made set a timer with a value whose jiffies
 319 .\"O representation exceeds
 320 .\"O .B MAX_SEC_IN_JIFFIES
 321 .\"O (defined in
 322 .\"O .IR include/linux/jiffies.h ),
 323 .\"O then the timer is silently truncated to this ceiling value.
 324 .\"O On Linux/i386 (where, since Linux 2.6.13,
 325 .\"O the default jiffy is 0.004 seconds),
 326 .\"O this means that the ceiling value for a timer is
 327 .\"O approximately 99.42 days.
 328 要求が jiffy 表現で
 329 .RI ( include/linux/jiffies.h
 330 で定義されている)
 331 .B MAX_SEC_IN_JIFFIES
 332 を越える値をタイマーに設定しようとするものの場合、
 333 タイマーは暗黙にこの上限値に切り詰められる。
 334 Linux/i386 の場合 (Linux 2.6.13 以降では jiffy は 0.004 秒) の場合、
 335 これはタイマーの上限値がおよそ 99.42 日になることを意味する。
 336 .\"O Since Linux 2.6.16,
 337 .\"O the kernel uses a different internal representation for times,
 338 .\"O and this ceiling is removed.
 339 Linux 2.6.16 以降では、カーネルは時間に関する内部表現として
 340 異なる表現を使うようになっており、この上限はなくなった。
 341
 342 .\"O On certain systems (including i386),
 343 .\"O Linux kernels before version 2.6.12 have a bug which will produce
 344 .\"O premature timer expirations of up to one jiffy under some circumstances.
 345 .\"O This bug is fixed in kernel 2.6.12.
 346 (i386 を含む) いくつかのシステムでは、
 347 バージョン 2.6.12 以前の Linux カーネルは
 348 ある種の状況では 1 jiffy 早くタイマーが終了してしまうというバグがあった。
 349 このバグはカーネル 2.6.12 で修正された。
 350 .\" 4 Jul 2005: It looks like this bug may remain in 2.4.x.
 351 .\"     http://lkml.org/lkml/2005/7/1/165
 352
 353 .\"O POSIX.1-2001 says that
 354 .\"O .BR setitimer ()
 355 .\"O should fail if a
 356 .\"O .I tv_usec
 357 .\"O value is specified that is outside of the range 0 to 999999.
 358 .\"O However, in kernels up to and including 2.6.21,
 359 .\"O Linux does not give an error, but instead silently
 360 .\"O adjusts the corresponding seconds value for the timer.
 361 POSIX.1-2001 では
 362 .BR setitimer ()
 363 は
 364 .I tv_usec
 365 の値が 0 から 999999 の範囲外である場合には失敗するべきだとしている。
 366 しかし、2.6.21 以前のカーネルの Linux ではエラーにならず、
 367 対応する秒数の分だけそのタイマーの秒の値が暗黙に調整される。
 368 .\"O From kernel 2.6.22 onward,
 369 .\"O this nonconformance has been repaired:
 370 .\"O an improper
 371 .\"O .I tv_usec
 372 .\"O value results in an
 373 .\"O .B EINVAL
 374 .\"O error.
 375 カーネル 2.6.22 以降では、この標準非準拠の動作は修正され、
 376 .I tv_usec
 377 の値が不適切な場合には
 378 .B EINVAL
 379 エラーとなる。
 380 .\" Bugzilla report 25 Apr 2006:
 381 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
 382 .\" "setitimer() should reject noncanonical arguments"
 383 .\"O .SH "SEE ALSO"
 384 .SH 関連項目
 385 .BR gettimeofday (2),
 386 .BR sigaction (2),
 387 .BR signal (2),
 388 .BR timer_create (2),
 389 .BR timerfd_create (2),
 390 .BR time (7)