settimeofday

名前

gettimeofday, settimeofday - 時刻を取得/設定する

書式

#include <sys/time.h>

int gettimeofday(struct timeval *tv, struct timezone *tz);

int settimeofday(const struct timeval *tv, const struct timezone *tz);

glibc 向けの機能検査マクロの要件 ( feature_test_macros(7) 参照):
settimeofday(): _BSD_SOURCE

説明

関数 gettimeofday() と settimeofday() は時刻とタイムゾーンを取得または設定する。 tv 引き数は struct timeval である ( <sys/time.h> で定義されている):

struct timeval {
    time_t      tv_sec;     /* 秒 */
    suseconds_t tv_usec;    /* マイクロ秒 */
};

これにより紀元 (the Epoch: time(2) を参照) からの秒とマイクロ秒が取得できる。 tz 引き数は struct timezone である:

struct timezone {
    int tz_minuteswest;     /* グリニッジ標準時との差 (西方に分単位) */
    int tz_dsttime;         /* 夏時間調整の型 */
};

tv や tz が NULL の場合、対応する構造体の設定/取得は行われない (ただし、 tv が NULL の場合には、コンパイル時の警告が発生する)。 timezone 構造体の利用は廃止予定とされている; 通常は tz 引き数に NULL を指定すべきである (下記の「注意」を参照)。 Linux では、 settimeofday() システムコールに関連して、独特の「クロックのズレ (warp clock)」が存在する場合がある。 これは (ブート後の) 最初の呼び出しで tz 引き数が NULL でなく、 tv 引き数が NULL で tz_minuteswest フィールド が 0 でない場合に起こる (この場合 tz_dsttime フィールドは 0 にすべきである)。 このような場合、 settimeofday() は CMOS クロックが地方時 (local time) であり、 UTC システム時間を得るためには、 tz_minuteswest の分だけ増加させなくてはなら ないとみなしてしまう。 疑いもなく、この機構を使うことは良い考えではない。

返り値

gettimeofday() と settimeofday() は成功すると 0 を返し、失敗した場合は -1 を返す (この場合は errno が適切に設定される)。

エラー

EFAULT

tv か tz のどちらかがアクセス可能なアドレス空間外を指している。

EINVAL

タイムゾーン (または他の何か) が不正である。

EPERM

呼び出し元プロセスに settimeofday() を呼び出すための十分な特権がない。 Linux では CAP_SYS_TIME ケーパビリティ (capability) が必要である。

準拠

SVr4, 4.3BSD に準拠する。 POSIX.1-2001 は gettimeofday() については記述しているが、 settimeofday() については記述していない。 POSIX.1-2008 では gettimeofday() は廃止予定とされており、 代わりに clock_gettime(2) の使用が推奨されている。

注意

gettimeofday() が返す時刻は、システム時間の不連続な変化 (例えば、システム管理者がシステム時間を手動で変更した場合など) の影響を 受ける。単調増加するクロックが必要な場合は、 clock_gettime(2) を参照してほしい。 timeval 構造体を操作するためのマクロの説明は timeradd(3) にある。 昔は struct timeval のフィールドは long 型であった。 tz_dsttime は Linux でこれまで使われたことはない。 したがって、以下は純粋に歴史的な興味から書かれたものである。 tz_dsttime フィールドには (下記に示す) シンボル定数が格納される。 これは一年のうちでいつ夏時間 (Daylight Savings Time) を実施するかを示している (注意: その値は年間を通した定数である: 夏時間が実施中であることを示すわけではなく、 アルゴリズムを選択しているだけである)。 夏時間は以下のように定義される:

DST_NONE     /* 夏時間を採用していない */
 
DST_USA      /* アメリカ合衆国式夏時間 */
 
DST_AUST     /* オーストラリア式夏時間 */
 
DST_WET      /* 西ヨーロッパ式夏時間 */
 
DST_MET      /* 中央ヨーロッパ式夏時間 */
 
DST_EET      /* 東ヨーロッパ式夏時間 */
 
DST_CAN      /* カナダ */
 
DST_GB       /* グレートブリテンおよびアイルランド */
 
DST_RUM      /* ルーマニア */
 
DST_TUR      /* トルコ */
 
DST_AUSTALT  /* 1986年に移行されたオーストラリア式 */

当然のことながら、夏時間がどの期間に実施されるかを国ごとの簡単なアルゴリズムで 導くことができないことが判明した。 実際、夏時間の期間は予測不可能な政治的決定で 決定される。そのため、この方法でタイムゾーンを表すことは断念された。 Linux において settimeofday() を呼び出すときは、 tz_dsttime フィールドを 0 にするべきである。

関連項目

date(1), adjtimex(2), clock_gettime(2), time(2), ctime(3), ftime(3), timeradd(3), capabilities(7), time(7)

この文書について

この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。