draft/man2/times.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   4 .\"
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\"
  25 .\" Modified by Michael Haardt (michael@moria.de)
  26 .\" Modified Sat Jul 24 14:29:17 1993 by Rik Faith (faith@cs.unc.edu)
  27 .\" Modified 961203 and 001211 and 010326 by aeb@cwi.nl
  28 .\" Modified 001213 by Michael Haardt (michael@moria.de)
  29 .\" Modified 13 Jun 02, Michael Kerrisk <mtk.manpages@gmail.com>
  30 .\"     Added note on nonstandard behavior when SIGCHLD is ignored.
  31 .\" Modified 2004-11-16, mtk, Noted that the nonconformance when
  32 .\"     SIGCHLD is being ignored is fixed in 2.6.9; other minor changes
  33 .\" Modified 2004-12-08, mtk, in 2.6 times() return value changed
  34 .\" 2005-04-13, mtk
  35 .\"     Added notes on nonstandard behavior: Linux allows 'buf' to
  36 .\"     be NULL, but POSIX.1 doesn't specify this and it's nonportable.
  37 .\"
  38 .\" Japanese Version Copyright (c) 1996 Satoshi Nozawa
  39 .\"         all rights reserved.
  40 .\" Translated 1996-06-25, Satoshi I. Nozawa <snozawa@env.sci.ibaraki.ac.jp>
  41 .\" Modified 1997-12-14, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  42 .\" Updated 2001-02-16, Kentaro Shirakata <argrath@ub32.org>
  43 .\" Updated 2001-04-10, Kentaro Shirakata <argrath@ub32.org>
  44 .\" Updated 2001-05-21, Kentaro Shirakata <argrath@ub32.org>
  45 .\" Updated 2002-10-21, Kentaro Shirakata <argrath@ub32.org>
  46 .\" Updated 2005-02-24, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  47 .\" Updated 2005-04-20, Kentaro Shirakata <argrath@ub32.org>
  48 .\" Updated 2008-02-12, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.77
  49 .\"
  50 .\" WORD:       clock ticks     クロック数
  51 .\"
  52 .TH TIMES 2 2008-06-25 "Linux" "Linux Programmer's Manual"
  53 .SH 名前
  54 times - プロセス時間を取得する
  55 .SH 書式
  56 .B #include <sys/times.h>
  57 .sp
  58 .BI "clock_t times(struct tms *" buf );
  59 .SH 説明
  60 .\"O .BR times ()
  61 .\"O stores the current process times in the
  62 .\"O .B "struct tms"
  63 .\"O that
  64 .\"O .I buf
  65 .\"O points to.
  66 .BR times ()
  67 は現在のプロセス時間を
  68 .I buf
  69 が指している
  70 .B "struct tms"
  71 に格納する。
  72 .\"O The
  73 .\"O .I struct tms
  74 .\"O is as defined in
  75 .\"O .IR <sys/times.h> :
  76 .I struct tms
  77 は
  78 .I <sys/times.h>
  79 で以下のように定義されている:
  80 .sp
  81 .in +4n
  82 .nf
  83 struct tms  {
  84     clock_t tms_utime;  /* user time */
  85     clock_t tms_stime;  /* system time */
  86     clock_t tms_cutime; /* user time of children */
  87     clock_t tms_cstime; /* system time of children */
  88 };
  89 .fi
  90 .in
  91 .LP
  92 .\"O The
  93 .\"O .I tms_utime
  94 .\"O field contains the CPU time spent executing instructions
  95 .\"O of the calling process.
  96 .I tms_utime
  97 フィールドは、呼び出したプロセスが命令を実行するのに消費した
  98 CPU 時間である。
  99 .\"O The
 100 .\"O .I tms_stime
 101 .\"O field contains the CPU time spent in the system while
 102 .\"O executing tasks on behalf of the calling process.
 103 .I tms_stime
 104 フィールドは、呼び出したプロセスのために実行されたタスクで、
 105 システムが消費した CPU 時間である。
 106 .\"O The
 107 .\"O .I tms_cutime
 108 .\"O field contains the sum of the
 109 .\"O .I tms_utime
 110 .\"O and
 111 .\"O .I tms_cutime
 112 .\"O values for all waited-for terminated children.
 113 .I tms_cutime
 114 フィールドは、
 115 終了を待っている全ての子プロセスの
 116 .I tms_utime
 117 と
 118 .I tms_cutime
 119 の合計である。
 120 .\"O The
 121 .\"O .I tms_cstime
 122 .\"O field contains the sum of the
 123 .\"O .I tms_stime
 124 .\"O and
 125 .\"O .I tms_cstime
 126 .\"O values for all waited-for terminated children.
 127 .I tms_cstime
 128 フィールドは、
 129 終了を待っている全ての子プロセスの
 130 .I tms_stime
 131 と
 132 .I tms_cstime
 133 の合計である。
 134 .LP
 135 .\"O Times for terminated children (and their descendants)
 136 .\"O are added in at the moment
 137 .\"O .BR wait (2)
 138 .\"O or
 139 .\"O .BR waitpid (2)
 140 .\"O returns their process ID.
 141 .\"O In particular, times of grandchildren
 142 .\"O that the children did not wait for are never seen.
 143 終了する子(及びその子孫)プロセスの時間は
 144 .BR wait (2)
 145 や
 146 .BR waitpid (2)
 147 がプロセス ID を返した瞬間に加算される。
 148 つまり、子がまだ終了を待っていない状態では
 149 孫プロセスの時間は決して現れない。
 150 .LP
 151 .\"O All times reported are in clock ticks.
 152 全ての時間はクロック数で返される。
 153 .\"O .SH "RETURN VALUE"
 154 .SH 返り値
 155 .\"O The function
 156 .\"O .BR times ()
 157 .\"O returns the number of clock ticks that have elapsed since
 158 .\"O an arbitrary point in the past.
 159 .\"O The return value may overflow the possible range of type
 160 .\"O .IR clock_t .
 161 .\"O On error, \fI(clock_t)\ \-1\fP is returned, and
 162 .\"O .I errno
 163 .\"O is set appropriately.
 164 .BR times ()
 165 は過去のある時点から経過したクロック数 (clock tick) を返す。
 166 この返り値は
 167 .I clock_t
 168 型が取り得る範囲からオーバーフローするかもしれない。
 169 エラーの場合、\fI(clock_t)\ \-1\fP が返され、
 170 .I errno
 171 が適切に設定される。
 172 .\" The only possible error is EFAULT.
 173 .\"O .SH "CONFORMING TO"
 174 .SH 準拠
 175 SVr4, 4.3BSD, POSIX.1-2001.
 176 .\"O .SH NOTES
 177 .SH 注意
 178 .\"O The number of clock ticks per second can be obtained using:
 179 .\"O .in +4n
 180 .\"O
 181 .\"O sysconf(_SC_CLK_TCK);
 182 .\"O .in
 183 一秒あたりのクロック数は
 184 .in +4n
 185
 186 sysconf(_SC_CLK_TCK);
 187
 188 .in
 189 を使って得ることが出来る。
 190 .PP
 191 .\"O In POSIX.1-1996 the symbol \fBCLK_TCK\fP (defined in
 192 .\"O .IR <time.h> )
 193 .\"O is mentioned as obsolescent.
 194 .\"O It is obsolete now.
 195 POSIX.1-1996 では、\fBCLK_TCK\fP シンボル
 196 .RI ( <time.h>
 197 で定義されている) は古いものであると記述されている。
 198 今ではこれは古いものである。
 199 .PP
 200 .\"O In Linux kernel versions before 2.6.9,
 201 .\"O if the disposition of
 202 .\"O .B SIGCHLD
 203 .\"O is set to
 204 .\"O .B SIG_IGN
 205 .\"O then the times of terminated children
 206 .\"O are automatically included in the
 207 .\"O .I tms_cstime
 208 .\"O and
 209 .\"O .I tms_cutime
 210 .\"O fields, although POSIX.1-2001 says that this should only happen
 211 .\"O if the calling process
 212 .\"O .BR wait (2)s
 213 .\"O on its children.
 214 .\"O +This nonconformance is rectified in Linux 2.6.9 and later.
 215 Linux 2.6.9 より前のバージョンでは、
 216 .B SIGCHLD
 217 を
 218 .B SIG_IGN
 219 に設定すると
 220 終了した子プロセスの回数は
 221 自動的に
 222 .I tms_cstime
 223 と
 224 .I tms_cutime
 225 フィールドに含まれる。
 226 しかし、POSIX.1-2001 では、この動作は呼び出し元が
 227 .BR wait (2)
 228 関数群で子プロセスを待った場合にのみ起きるべきだとしている。
 229 標準とは異なるこの動作は Linux 2.6.9 以降で修正されている。
 230 .\"O .\" See the description of times() in XSH, which says:
 231 .\"O .\"        The times of a terminated child process are included... when wait()
 232 .\"O .\"        or waitpid() returns the process ID of this terminated child.
 233 .\" See the description of times() in XSH, which says:
 234 .\"     The times of a terminated child process are included... when wait()
 235 .\"     or waitpid() returns the process ID of this terminated child.
 236
 237 .\"O On Linux, the
 238 .\"O .I buf
 239 .\"O argument can be specified as NULL, with the result that
 240 .\"O .BR times ()
 241 .\"O just returns a function result.
 242 Linux では、
 243 .I buf
 244 引数に NULL を指定することができ、その場合は
 245 .BR times ()
 246 は単に関数の結果を返す。
 247 .\"O However, POSIX does not specify this behavior, and most
 248 .\"O other UNIX implementations require a non-NULL value for
 249 .\"O .IR buf .
 250 しかし、POSIX はこの振る舞いは規定されておらず、
 251 その他のほとんどの UNIX 実装は
 252 .I buf
 253 の値として非 NULL の値を要求する。
 254 .LP
 255 .\"O Note that
 256 .\"O .BR clock (3)
 257 .\"O also returns a value of type
 258 .\"O .IR clock_t ,
 259 .\"O but this value is measured in units of
 260 .\"O .BR CLOCKS_PER_SEC ,
 261 .\"O not the clock ticks used by
 262 .\"O .BR times ().
 263 .BR clock (3)
 264 も
 265 .I clock_t
 266 型の値を返すが、この値は
 267 .BR times ()
 268 で使用されるクロック tick 数ではなく、
 269 .B CLOCKS_PER_SEC
 270 が単位である点に注意すること。
 271
 272 .\"O On Linux, the "arbitrary point in the past" from which the return value of
 273 .\"O .BR times ()
 274 .\"O is measured has varied across kernel versions.
 275 .\"O On Linux 2.4 and earlier this point is the moment the system was booted.
 276 .\"O Since Linux 2.6, this point is \fI(2^32/HZ) \- 300\fP
 277 .\"O (i.e., about 429 million) seconds before system boot time.
 278 .\"O This variability across kernel versions (and across UNIX implementations),
 279 .\"O combined with the fact that the returned value may overflow the range of
 280 .\"O .IR clock_t ,
 281 .\"O means that a portable application would be wise to avoid using this value.
 282 .\"O To measure changes in elapsed time, use
 283 .\"O .BR gettimeofday (2)
 284 .\"O instead.
 285 Linux では、
 286 .BR times ()
 287 の返り値を計算する起点となる「過去の任意の時点」は、カーネルのバージョン
 288 により異なる。
 289 Linux 2.4 以前では、この時点はシステムが起動した瞬間である。
 290 Linux 2.6 以降では、この時点はシステム起動時刻の \fI(2^32/HZ) \- 300\fP
 291 (および 4億2900万) 秒前である。
 292 このようにカーネルバージョン (や UNIX の実装) により異なることと、
 293 返り値が
 294 .I clock_t
 295 の範囲をオーバーフローする可能性があるという事実を考慮すると、
 296 移植性が必要なアプリケーションではこの値を使うのは避けるのが賢明であろう。
 297 経過時間を測りたい場合には、代わりに
 298 .BR gettimeofday (2)
 299 を使用すること。
 300 .\" .PP
 301 .\"O .\" On older systems the number of clock ticks per second is given
 302 .\"O .\" by the variable HZ.
 303 .\" 古いシステムでは一秒あたりのクロック数は HZ 変数で与えられる。
 304 .\"O .SS "Historical"
 305 .SS 歴史
 306 .\"O SVr1-3 returns
 307 .\"O .I long
 308 .\"O and the struct members are of type
 309 .\"O .I time_t
 310 .\"O although they store clock ticks, not seconds since the Epoch.
 311 .\"O V7 used
 312 .\"O .I long
 313 .\"O for the struct members, because it had no type
 314 .\"O .I time_t
 315 .\"O yet.
 316 SVr1-3 では
 317 .I long
 318 を返し、構造体のメンバに
 319 .I time_t
 320 型を使っていたが、紀元からの秒数ではなくクロック数を格納していた。
 321 V7 では構造体のメンバに
 322 .I long
 323 型を使っていた。まだ
 324 .I time_t
 325 型がなかったからである。
 326 .\"O .SH BUGS
 327 .SH バグ
 328 .\"O A limitation of the Linux system call conventions on some architectures
 329 .\"O (notably i386) means that on Linux 2.6 there is a small time window
 330 .\"O (41 seconds) soon after boot when
 331 .\"O .BR times ()
 332 .\"O can return \-1, falsely indicating that an error occurred.
 333 .\"O The same problem can occur when the return value wraps passed
 334 .\"O the maximum value that can be stored in
 335 .\"O .BR clockid_t .
 336 いくつかのアーキテクチャ (特に i386) における Linux のシステムコールの慣習の
 337 制限により、Linux 2.6 では起動直後は (41秒と) タイムウィンドウが小さく、
 338 .BR times ()
 339 がエラーが起こったことを示す \-1 を間違って返すことがある。
 340 返り値が
 341 .I clockid_t
 342 が格納可能な最大値を超過した際にも同じ問題が起こり得る。
 343 .\" The problem is that a syscall return of -4095 to -1
 344 .\" is interpreted by glibc as an error, and the wrapper converts
 345 .\" the return value to -1.
 346 .\" http://marc.info/?l=linux-kernel&m=119447727031225&w=2
 347 .\" "compat_sys_times() bogus until jiffies >= 0"
 348 .\" November 2007
 349 .\"O .SH "SEE ALSO"
 350 .SH 関連項目
 351 .BR time (1),
 352 .BR getrusage (2),
 353 .BR wait (2),
 354 .BR clock (3),
 355 .BR sysconf (3),
 356 .BR time (7)