release/man2/gettimeofday.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 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\-12 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 .\" The following is covered under EPERM below:
  88 .\" .PP
  89 .\" Only the superuser may use
  90 .\" .BR settimeofday ().
  91 \fItv\fP や \fItz\fP が NULL の場合、対応する構造体の設定/取得は行われない
  92 (ただし、\fItv\fP が NULL の場合には、コンパイル時の警告が発生する)。
  93 .PP
  94 \fItimezone\fP 構造体の利用は廃止予定とされている;
  95 通常は \fItz\fP 引き数に NULL を指定すべきである (下記の「注意」を参照)。
  96
  97 Linux では、 \fBsettimeofday\fP() システムコールに関連して、独特の「クロックのズレ
  98 (warp clock)」が存在する場合がある。 これは (ブート後の) 最初の呼び出しで
  99 \fItz\fP 引き数が NULL でなく、 \fItv\fP 引き数が NULL で \fItz_minuteswest\fP フィールド
 100 が 0 でない場合に起こる (この場合 \fItz_dsttime\fP フィールドは 0 にすべきである)。
 101 このような場合、 \fBsettimeofday\fP() は CMOS クロックが地方時 (local time) であり、
 102 UTC システム時間を得るためには、\fItz_minuteswest\fP の分だけ増加させなくてはなら
 103 ないとみなしてしまう。 疑いもなく、この機構を使うことは良い考えではない。
 104 .SH 返り値
 105 \fBgettimeofday\fP()  と \fBsettimeofday\fP()  は成功すると 0 を返し、失敗した場合は \-1 を返す (この場合は
 106 \fIerrno\fP が適切に設定される)。
 107 .SH エラー
 108 .TP
 109 \fBEFAULT\fP
 110 \fItv\fP か \fItz\fP のどちらかがアクセス可能なアドレス空間外を指している。
 111 .TP
 112 \fBEINVAL\fP
 113 タイムゾーン (または他の何か) が不正である。
 114 .TP
 115 \fBEPERM\fP
 116 呼び出し元プロセスに \fBsettimeofday\fP()  を呼び出すための十分な特権がない。 Linux では \fBCAP_SYS_TIME\fP
 117 ケーパビリティ (capability) が必要である。
 118 .SH 準拠
 119 SVr4, 4.3BSD に準拠する。 POSIX.1\-2001 は \fBgettimeofday\fP()  については記述しているが、
 120 \fBsettimeofday\fP()  については記述していない。 POSIX.1\-2008 では \fBgettimeofday\fP()
 121 は廃止予定とされており、 代わりに \fBclock_gettime\fP(2)  の使用が推奨されている。
 122 .SH 注意
 123 \fItimeval\fP 構造体を操作するためのマクロの説明は \fBtimeradd\fP(3)  にある。
 124
 125 昔は \fIstruct timeval\fP のフィールドは \fIlong\fP 型であった。
 126
 127 .\" it has not
 128 .\" been and will not be supported by libc or glibc.
 129 .\" Each and every occurrence of this field in the kernel source
 130 .\" (other than the declaration) is a bug.
 131 \fItz_dsttime\fP は Linux でこれまで使われたことはない。
 132 したがって、以下は純粋に歴史的な興味から書かれたものである。
 133
 134 \fItz_dsttime\fP フィールドには (下記に示す) シンボル定数が格納される。
 135 これは一年のうちでいつ夏時間 (Daylight Savings Time) を実施するかを示している
 136 (注意: その値は年間を通した定数である: 夏時間が実施中であることを示すわけではなく、
 137 アルゴリズムを選択しているだけである)。 夏時間は以下のように定義される:
 138 .in +4n
 139 .nf
 140
 141 \fBDST_NONE\fP     /* 夏時間を採用していない */
 142 .br
 143 \fBDST_USA\fP      /* アメリカ合衆国式夏時間 */
 144 .br
 145 \fBDST_AUST\fP     /* オーストラリア式夏時間 */
 146 .br
 147 \fBDST_WET\fP      /* 西ヨーロッパ式夏時間 */
 148 .br
 149 \fBDST_MET\fP      /* 中央ヨーロッパ式夏時間 */
 150 .br
 151 \fBDST_EET\fP      /* 東ヨーロッパ式夏時間 */
 152 .br
 153 \fBDST_CAN\fP      /* カナダ */
 154 .br
 155 \fBDST_GB\fP       /* グレートブリテンおよびアイルランド */
 156 .br
 157 \fBDST_RUM\fP      /* ルーマニア */
 158 .br
 159 \fBDST_TUR\fP      /* トルコ */
 160 .br
 161 \fBDST_AUSTALT\fP  /* 1986年に移行されたオーストラリア式 */
 162 .fi
 163 .in
 164 .PP
 165 当然のことながら、夏時間がどの期間に実施されるかを国ごとの簡単なアルゴリズムで
 166 導くことができないことが判明した。 実際、夏時間の期間は予測不可能な政治的決定で
 167 決定される。そのため、この方法でタイム・ゾーンを表すことは断念された。
 168 Linux において \fBsettimeofday\fP() を呼び出すときは、
 169 \fItz_dsttime\fP フィールドを 0 にするべきである。
 170 .SH 関連項目
 171 \fBdate\fP(1), \fBadjtimex\fP(2), \fBtime\fP(2), \fBctime\fP(3), \fBftime\fP(3),
 172 \fBtimeradd\fP(3), \fBcapabilities\fP(7), \fBtime\fP(7)