draft/man2/gettimeofday.2

   1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   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 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified by Michael Haardt (michael@moria.de)
  26 .\" Modified 1993-07-23 by Rik Faith (faith@cs.unc.edu)
  27 .\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com):
  28 .\"   Fixed necessary '#include' lines.
  29 .\" Modified 1995-04-15 by Michael Chastain (mec@shell.portal.com):
  30 .\"   Added reference to adjtimex.
  31 .\" Removed some nonsense lines pointed out by Urs Thuermann,
  32 .\"   (urs@isnogud.escape.de), aeb, 950722.
  33 .\" Modified 1997-01-14 by Austin Donnelly (and1000@debian.org):
  34 .\"   Added return values section, and bit on EFAULT
  35 .\" Added clarification on timezone, aeb, 971210.
  36 .\" Removed "#include <unistd.h>", aeb, 010316.
  37 .\" Modified, 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
  38 .\"   Added notes on capability requirement.
  39 .\"
  40 .\"*******************************************************************
  41 .\"
  42 .\" This file was generated with po4a. Translate the source file.
  43 .\"
  44 .\"*******************************************************************
  45 .TH GETTIMEOFDAY 2 2012\-04\-26 Linux "Linux Programmer's Manual"
  46 .SH 名前
  47 gettimeofday, settimeofday \- 時刻を取得/設定する
  48 .SH 書式
  49 .nf
  50 \fB#include <sys/time.h>\fP
  51
  52 \fBint gettimeofday(struct timeval *\fP\fItv\fP\fB, struct timezone *\fP\fItz\fP\fB);\fP
  53
  54 \fBint settimeofday(const struct timeval *\fP\fItv\fP\fB, const struct timezone *\fP\fItz\fP\fB);\fP
  55
  56 .fi
  57 .in -4n
  58 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  59 .in
  60 .sp
  61 \fBsettimeofday\fP(): _BSD_SOURCE
  62 .SH 説明
  63 関数 \fBgettimeofday\fP()  と \fBsettimeofday\fP()  は時刻とタイムゾーンを取得または設定する。 \fItv\fP 引き数は
  64 \fIstruct timeval\fP である (\fI<sys/time.h>\fP で定義されている):
  65 .sp
  66 .in +4n
  67 .nf
  68 struct timeval {
  69     time_t      tv_sec;     /* 秒 */
  70     suseconds_t tv_usec;    /* マイクロ秒 */
  71 };
  72 .fi
  73 .in
  74 .sp
  75 これにより紀元 (the Epoch: \fBtime\fP(2)  を参照) からの秒とマイクロ秒が取得できる。 \fItz\fP 引き数は \fIstruct
  76 timezone\fP である:
  77 .sp
  78 .in +4n
  79 .nf
  80 struct timezone {
  81     int tz_minuteswest;     /* グリニッジ標準時との差 (西方に分単位) */
  82     int tz_dsttime;         /* 夏時間調整の型 */
  83 };
  84 .fi
  85 .in
  86 .PP
  87 .\" FIXME The compilation warning looks to be going away in 2.17
  88 .\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8
  89 .\" The following is covered under EPERM below:
  90 .\" .PP
  91 .\" Only the superuser may use
  92 .\" .BR settimeofday ().
  93 \fItv\fP や \fItz\fP が NULL の場合、対応する構造体の設定/取得は行われない
  94 (ただし、\fItv\fP が NULL の場合には、コンパイル時の警告が発生する)。
  95 .PP
  96 \fItimezone\fP 構造体の利用は廃止予定とされている;
  97 通常は \fItz\fP 引き数に NULL を指定すべきである (下記の「注意」を参照)。
  98
  99 Linux では、 \fBsettimeofday\fP() システムコールに関連して、独特の「クロックのズレ
 100 (warp clock)」が存在する場合がある。 これは (ブート後の) 最初の呼び出しで
 101 \fItz\fP 引き数が NULL でなく、 \fItv\fP 引き数が NULL で \fItz_minuteswest\fP フィールド
 102 が 0 でない場合に起こる (この場合 \fItz_dsttime\fP フィールドは 0 にすべきである)。
 103 このような場合、 \fBsettimeofday\fP() は CMOS クロックが地方時 (local time) であり、
 104 UTC システム時間を得るためには、\fItz_minuteswest\fP の分だけ増加させなくてはなら
 105 ないとみなしてしまう。 疑いもなく、この機構を使うことは良い考えではない。
 106 .SH 返り値
 107 \fBgettimeofday\fP()  と \fBsettimeofday\fP()  は成功すると 0 を返し、失敗した場合は \-1 を返す (この場合は
 108 \fIerrno\fP が適切に設定される)。
 109 .SH エラー
 110 .TP
 111 \fBEFAULT\fP
 112 \fItv\fP か \fItz\fP のどちらかがアクセス可能なアドレス空間外を指している。
 113 .TP
 114 \fBEINVAL\fP
 115 タイムゾーン (または他の何か) が不正である。
 116 .TP
 117 \fBEPERM\fP
 118 呼び出し元プロセスに \fBsettimeofday\fP()  を呼び出すための十分な特権がない。 Linux では \fBCAP_SYS_TIME\fP
 119 ケーパビリティ (capability) が必要である。
 120 .SH 準拠
 121 SVr4, 4.3BSD に準拠する。 POSIX.1\-2001 は \fBgettimeofday\fP()  については記述しているが、
 122 \fBsettimeofday\fP()  については記述していない。 POSIX.1\-2008 では \fBgettimeofday\fP()
 123 は廃止予定とされており、 代わりに \fBclock_gettime\fP(2)  の使用が推奨されている。
 124 .SH 注意
 125 \fBgettimeofday\fP() が返す時刻は、システム時間の不連続な変化
 126 (例えば、システム管理者がシステム時間を手動で変更した場合など)
 127 の影響を\fI受ける\fP。単調増加するクロックが必要な場合は、
 128 \fBclock_gettime\fP(2) を参照してほしい。
 129
 130 \fItimeval\fP 構造体を操作するためのマクロの説明は \fBtimeradd\fP(3)  にある。
 131
 132 昔は \fIstruct timeval\fP のフィールドは \fIlong\fP 型であった。
 133
 134 .\" it has not
 135 .\" been and will not be supported by libc or glibc.
 136 .\" Each and every occurrence of this field in the kernel source
 137 .\" (other than the declaration) is a bug.
 138 \fItz_dsttime\fP は Linux でこれまで使われたことはない。
 139 したがって、以下は純粋に歴史的な興味から書かれたものである。
 140
 141 \fItz_dsttime\fP フィールドには (下記に示す) シンボル定数が格納される。
 142 これは一年のうちでいつ夏時間 (Daylight Savings Time) を実施するかを示している
 143 (注意: その値は年間を通した定数である: 夏時間が実施中であることを示すわけではなく、
 144 アルゴリズムを選択しているだけである)。 夏時間は以下のように定義される:
 145 .in +4n
 146 .nf
 147
 148 \fBDST_NONE\fP     /* 夏時間を採用していない */
 149 .br
 150 \fBDST_USA\fP      /* アメリカ合衆国式夏時間 */
 151 .br
 152 \fBDST_AUST\fP     /* オーストラリア式夏時間 */
 153 .br
 154 \fBDST_WET\fP      /* 西ヨーロッパ式夏時間 */
 155 .br
 156 \fBDST_MET\fP      /* 中央ヨーロッパ式夏時間 */
 157 .br
 158 \fBDST_EET\fP      /* 東ヨーロッパ式夏時間 */
 159 .br
 160 \fBDST_CAN\fP      /* カナダ */
 161 .br
 162 \fBDST_GB\fP       /* グレートブリテンおよびアイルランド */
 163 .br
 164 \fBDST_RUM\fP      /* ルーマニア */
 165 .br
 166 \fBDST_TUR\fP      /* トルコ */
 167 .br
 168 \fBDST_AUSTALT\fP  /* 1986年に移行されたオーストラリア式 */
 169 .fi
 170 .in
 171 .PP
 172 当然のことながら、夏時間がどの期間に実施されるかを国ごとの簡単なアルゴリズムで
 173 導くことができないことが判明した。 実際、夏時間の期間は予測不可能な政治的決定で
 174 決定される。そのため、この方法でタイム・ゾーンを表すことは断念された。
 175 Linux において \fBsettimeofday\fP() を呼び出すときは、
 176 \fItz_dsttime\fP フィールドを 0 にするべきである。
 177 .SH 関連項目
 178 \fBdate\fP(1), \fBadjtimex\fP(2), \fBclock_gettime\fP(2), \fBtime\fP(2),
 179 \fBctime\fP(3), \fBftime\fP(3), \fBtimeradd\fP(3), \fBcapabilities\fP(7),
 180 \fBtime\fP(7)
 181 .SH この文書について
 182 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 183 である。プロジェクトの説明とバグ報告に関する情報は
 184 http://www.kernel.org/doc/man\-pages/ に書かれている。