CLOCK_GETRES

Section: Linux Programmer's Manual (2)
Updated: 2020-04-11
Index Return to Main Contents

名前

clock_getres, clock_gettime, clock_settime - クロックと時間の関数

書式

#include <time.h>

int clock_getres(clockid_t clockid, struct timespec *res);

int clock_gettime(clockid_t clockid, struct timespec *tp);

int clock_settime(clockid_t clockid, const struct timespec *tp);

-lrt とリンクする (バージョン 2.17 より前の glibc のみ)

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

clock_getres(), clock_gettime(), clock_settime():

: _POSIX_C_SOURCE >= 199309L

説明

関数 clock_getres() は指定されたクロック clockid の分解能 (精度) を探し出す。 res が NULL でない場合、その分解能を res で指される struct timespec に格納する。クロックの分解能は実装に依存し、特定のプロセスによって設定することはできない。 clock_settime() の引き数 tp で指される時間の値が res の倍数でない場合、 res の倍数に切り詰められる。

関数 clock_gettime() と clock_settime() は、指定されたクロック clockid の時間を取得または設定する。

res と tp 引き数は timespec 構造体であり、 <time.h> で以下のように規定されている:

struct timespec {
time_t tv_sec; /* seconds */
long tv_nsec; /* nanoseconds */ };

clockid 引き数は特定のクロックの識別子であり、そのクロックで動作する。クロックはシステム全体に適用することもでき、その場合は全てのプロセスから見ることができる。また 1 つのプロセス内でのみ時間を計測する場合は、プロセス毎に適用することもできる。

全ての実装においてシステム全体のリアルタイムクロックがサポートされ、 CLOCK_REALTIME で識別される。時間は紀元 (the Epoch) からの秒とナノ秒で表される。時間が変更された場合、相対的な時間間隔のタイマーは影響を受けないが、絶対的な時点のタイマーは影響を受ける。

さらにいくつかのクロックが実装されているかもしれない。対応する時間の値を解釈する方法とタイマーへの影響は、定められていない。

glibc と Linux カーネルの最新のバージョンでは、以下のクロックがサポートされている。

CLOCK_REALTIME: 実時間を計測する設定可能なシステム全体で一意な時間。このクロックを設定するには適切な特権が必要である。このクロックは、システム時間の不連続な変化 (例えば、システム管理者がシステム時間を手動で変更した場合など) や adjtime や NTP が行う段階的な調整の影響を受ける。
: CLOCK_REALTIME_ALARM (Linux 3.0 以降; Linux 特有) CLOCK_REALTIME と似ているが、設定可能でない。より詳細は timer_create(2) を参照すること。
CLOCK_REALTIME_COARSE (Linux 2.6.32 以降; Linux 特有): 高速だが精度が低い CLOCK_REALTIME。速度が非常に必要で、かつ高精度のタイムスタンプが不要な場合に使用するとよい。アーキテクチャー毎のサポートが必要で、 vdso(7) において、このフラグのアーキテクチャーのサポートも多分必要である。
: CLOCK_TAI (Linux 3.10 以降; Linux 特有) 実際の経過時間 (wall-clock time) から派生した設定できないシステム全体のクロック。閏秒は無視する。このクロックでは、 CLOCK_REALTIME で発生するような、NTP での閏秒の追加による、不連続や巻き戻しが起こらない。
: 頭字語 TAI は International Atomic Time から来ている。
CLOCK_MONOTONIC: 設定することができないシステム全体のクロックで、 ---POSIX での記載では---「特に規定されない過去の時点」からの単調増加の時間で表現されるクロック。 Linux では、この時点は、システムがブートしてから稼働秒数に対応する。
: CLOCK_MONOTONIC クロックは、システム時間の不連続な変化 (例えば、システム管理者がシステム時間を手動で変更した場合など) の影響を受けないが、 adjtime(3) や NTP が行う段階的な調整の影響を受ける。このクロックは、システムがサスペンドしている時間をカウントしない。 CLOCK_MONOTONIC とその派生では、連続した呼び出しで返される時間が巻き戻らないことを保証しているが、連続した呼び出しでは---アーキテクチャによっては--- 同じ (増加していない) 時間を返すかもしれない。
CLOCK_MONOTONIC_COARSE (Linux 2.6.32 以降; Linux 特有): 高速だが精度が低い CLOCK_MONOTONIC。このクロックは設定可能ではない。速度が非常に必要で、かつ高精度のタイムスタンプが不要な場合に使用するとよい。アーキテクチャー毎のサポートが必要で、 vdso(7) において、このフラグのアーキテクチャーのサポートも多分必要である。
CLOCK_MONOTONIC_RAW (Linux 2.6.28 以降; Linux 特有): CLOCK_MONOTONIC と同様だが、NTP による調整や adjtime(3) が行う段階的な調整の影響を受けない、ハードウェアによる生の時刻へのアクセスができる。このクロックは、システムがサスペンドしている時間をカウントしない。
CLOCK_BOOTTIME (Linux 2.6.39 以降; Linux 固有): 設定できないシステム全体のクロックで、 CLOCK_MONOTONIC と同じだが、システムがサスペンドされている時間も含まれる点が異なる。これを使うと、アプリケーションはサスペンド状態も扱える "monotonic" なクロックを得ることができる。しかも、 CLOCK_REALTIME における複雑な処理を行う必要もなくなる。 CLOCK_REALTIME では、 settimeofday(2) などを使って時刻を変更した場合、時刻に不連続な変化が発生するからだ。
: CLOCK_BOOTTIME_ALARM (Linux 3.0 以降; Linux 特有) CLOCK_BOOTTIME と似ている。より詳細は timer_create(2) を参照すること。
CLOCK_PROCESS_CPUTIME_ID (Linux 2.6.12 以降): プロセスで消費される CPU 時間 (そのプロセスの全スレッドで消費される CPU 時間) を計測するクロック。 Linux では、このクロックは設定できない。
CLOCK_THREAD_CPUTIME_ID (Linux 2.6.12 以降): スレッドで消費される CPU 時間を計測するクロック。 Linux では、このクロックは設定できない。

Linux では、下記の動的クロックインスタンスも実装している。

動的クロック

上記のハードコードされた System-V スタイルのクロックに加え、 Linux は POSIX クロックの操作を特定のキャラクターデバイスでサポートしている。これらのデバイスは「動的」クロックと呼ばれ、Linux 2.6.39 からサポートされている。

適切なマクロを使うことで、オープンファイルディスクリプターをクロック ID に変換することができ、 clock_gettime(), clock_settime(), clock_adjtime(2) に渡すことができる。以下の例では、ファイルディスクリプターを動的クロック ID に変換する方法を示している。

#define CLOCKFD 3 #define FD_TO_CLOCKID(fd) ((~(clockid_t) (fd) << 3) | CLOCKFD) #define CLOCKID_TO_FD(clk) ((unsigned int) ~((clk) >> 3))

struct timeval tv; clockid_t clkid; int fd;

fd = open("/dev/ptp0", O_RDWR); clkid = FD_TO_CLOCKID(fd); clock_gettime(clkid, &tv);

返り値

clock_gettime(), clock_settime(), clock_getres() は成功した場合に 0 を返し、失敗した場合に -1 を返す (失敗した場合、 errno が適切に設定される)。

エラー

EFAULT: tp がアクセス可能なアドレス空間の外を指した。
EINVAL: 指定された clockid が、以下のいずれかの理由で無効である。 System-V スタイルのハードコードされた正の値が範囲外である。または、動的クロック ID が有効なクロックオブジェクトのインスタンスを参照していない。
EINVAL: (clock_settime()): tp.tv_sec が負である。または、 tp.tv_nsec が範囲 [0..999,999,999] の外である。
EINVAL: clock_settime() の呼び出しに指定された clockid が設定可能なクロックでない。
ENOTSUP: 指定された動的 POSIX クロックデバイスで、操作がサポートされていない。
: EINVAL (Linux 4.3 以降) CLOCK_REALTIME の clockid を指定して呼び出された clock_settime() で、 CLOCK_MONOTONIC クロックの現在の値よりも小さい値の時間を設定しようとした。
ENODEV: 動的な clockid で表される (例えば USB のような) ホットプラグデバイスが、キャラクターデバイスのオープン後になくなった。
EPERM: 指示されたクロックを設定する権限が clock_settime() にない。
EACCES: clock_settime() が指定された動的 POSIX クロックデバイスに対して書き込み権限がない。

バージョン

これらのシステムコールは Linux 2.6 で初めて登場した。

属性

このセクションで使われる用語の説明は、 attributes(7) を参照すること。

インタフェース	属性	値
clock_getres(), clock_gettime(), clock_settime()	スレッドセーフ性	MT セーフ

準拠

POSIX.1-2001, POSIX.1-2008, SUSv2.

可用性

これらの関数が利用可能な POSIX システムでは、<unistd.h> においてシンボル _POSIX_TIMERS が 0 より大きい値に定義されている。シンボル _POSIX_MONOTONIC_CLOCK, _POSIX_CPUTIME, _POSIX_THREAD_CPUTIME は CLOCK_MONOTONIC, CLOCK_PROCESS_CPUTIME_ID, CLOCK_THREAD_CPUTIME_ID が利用可能なことを示す。 (sysconf(3) も参照すること。)

注意

POSIX.1 では以下のように規定されている:

: CLOCK_REALTIME クロックの値を clock_settime() を使って設定する場合、 nanosleep() を含む、このクロックに基づいた相対 (relative) タイムサービスの待ちでブロックしているスレッドや、このクロックに基づいた相対 (relative) タイマーの期限切れの影響を受けない。結果として、これらのタイムサービスは、クロックの新しい値や古い値とは関係なく、要求された相対時間が経過した場合に、期限切れとなる。

POSIX.1-2001 では、「適切な特権 (appropriate privileges)」を持ったプロセスは、 clock_settime() を使って、クロック CLOCK_PROCESS_CPUTIME_ID と CLOCK_THREAD_CPUTIME_ID を設定することができるとされている。 Linux では、これらのクロックは設定可能ではない (すなわち、どのプロセスも「適切な特権」を持たない)。

C ライブラリ/カーネルの違い

アーキテクチャによっては、 clock_gettime() の実装は、 vdso(7) で提供されている。

SMP システムに関する歴史的な注意事項

Linux が CLOCK_PROCESS_CPUTIME_ID と CLOCK_THREAD_CPUTIME_ID クロックのカーネルによるサポートを追加する前は、 glibc はこれらのクロックは多くのプラットフォームで CPU のタイマーレジスター (i386 上の TSC、Itanium 上の AR.ITC) を用いて実現されていた。これらのレジスターは CPU 間で異なる可能性があり、プロセスが他の CPU に移動させられた場合、結果としてこれらのクロックが偽の結果 (bogus results) を返すかもしれない。

SMP システムの各 CPU が別々のクロック源を持つ場合、タイマーレジスター間の相互関係を管理する方法はない。これは各 CPU が微妙に異なる周波数で動作するためである。これが真実の場合 (訳註: 各 CPU が別々のクロック源を持つ場合)、 clock_getcpuclockid(0) は ENOENT を返して、その状況を表す。 2 つのクロックは、プロセスが特定の CPU 上に留まっていることが保証できる場合にのみ有効である。

SMP システムの各プロセッサは全く同じ時刻に起動する訳ではないので、各タイマーレジスターは通常はあるオフセットで動作している。オフセットをブート時に制限するコードが含まれるアーキテクチャーもある。しかし、このコードがオフセットを正確に調整することは保証できない。 glibc は (Linux カーネルとは異なり) オフセットを扱うためのコードを提供しない。通常はこれらのオフセットが小さいので、多くの場合でその影響は無視できる。

glibc 2.4 以降では、このページで説明したシステムコールのラッパー関数は、 CLOCK_PROCESS_CPUTIME_ID と CLOCK_THREAD_CPUTIME_ID のカーネル実装が利用できるシステム (すなわち Linux 2.6.12 以降) ではカーネル実装を利用することで、上述の問題を回避している。

例

以下のプログラムは、 clock_gettime() と clock_getres() のいろいろなクロックでの使い方を示している。プログラムを実行する際に、見たい例になっているだろう。

$ ./clock_times x CLOCK_REALTIME : 1585985459.446 (18356 days + 7h 30m 59s)
     resolution:          0.000000001 CLOCK_TAI : 1585985496.447 (18356 days + 7h 31m 36s)
     resolution:          0.000000001 CLOCK_MONOTONIC: 52395.722 (14h 33m 15s)
     resolution:          0.000000001 CLOCK_BOOTTIME : 72691.019 (20h 11m 31s)
     resolution:          0.000000001

プログラムのソース

/* clock_times.c

Licensed under GNU General Public License v2 or later. */ #define _XOPEN_SOURCE 600 #include <time.h> #include <stdio.h> #include <stdlib.h> #include <stdbool.h> #include <unistd.h>

#define SECS_IN_DAY (24 * 60 * 60)

static void displayClock(clockid_t clock, char *name, bool showRes) {
struct timespec ts;

    if (clock_gettime(clock, &ts) == -1) {
        perror("clock_gettime");
        exit(EXIT_FAILURE);
    }

printf("%-15s: %10ld.%03ld (", name,
(long) ts.tv_sec, ts.tv_nsec / 1000000);

    long days = ts.tv_sec / SECS_IN_DAY;
    if (days > 0)
        printf("%ld days + ", days);

    printf("%2ldh %2ldm %2lds", (ts.tv_sec % SECS_IN_DAY) / 3600,
            (ts.tv_sec % 3600) / 60, ts.tv_sec % 60);
    printf(")\n");

    if (clock_getres(clock, &ts) == -1) {
        perror("clock_getres");
        exit(EXIT_FAILURE);
    }

    if (showRes)
        printf("     resolution: %10ld.%09ld\n",
                (long) ts.tv_sec, ts.tv_nsec); }

int main(int argc, char *argv[]) {
bool showRes = argc > 1;

    displayClock(CLOCK_REALTIME, "CLOCK_REALTIME", showRes); #ifdef CLOCK_TAI
    displayClock(CLOCK_TAI, "CLOCK_TAI", showRes); #endif
    displayClock(CLOCK_MONOTONIC, "CLOCK_MONOTONIC", showRes); #ifdef CLOCK_BOOTTIME
    displayClock(CLOCK_BOOTTIME, "CLOCK_BOOTTIME", showRes); #endif
    exit(EXIT_SUCCESS); }