ctime(3)

asctime, asctime_r, ctime, ctime_r, difftime, gmtime, gmtime_r, localtime, localtime_r, mktime, timegm − バイナリ日付と時刻の値を変換する

標準 C ライブラリ (libc, −lc)

#include <time.h>

extern char *tzname[2];

char *

ctime(const time_t *clock);

double

difftime(time_t time1, time_t time0);

char *

asctime(const struct tm *tm);

struct tm *

localtime(const time_t *clock);

struct tm *

gmtime(const time_t *clock);

time_t

mktime(struct tm *tm);

time_t

timegm(struct tm *tm);

char *

ctime_r(const time_t *clock, char *buf);

struct tm *

localtime_r(const time_t *clock, struct tm *result);

struct tm *

gmtime_r(const time_t *clock, struct tm *result);

char *

asctime_r(const struct tm *tm, char *buf);

解説

関数 ctime(), gmtime(), localtime() はすべて、基準時点 (00:00:00 UTC, 1970 年 1 月 1 日 time(3) を参照) 以降の時刻 (秒単位) を表す時間の値を引 数として取ります。

関数 localtime() は、 clock が指す時刻の値を変換し、現在の時間帯 (および 日光節約時間のような他の要素) に調整した後の値について細分化された時間情 報が入った ‘‘struct tm’’ (後述) を指すポインタを返します。時間帯調整は、 TZ 環境変数 ( tzset(3) を参照) で指定されたように実行されます。プロセスが tzset(3) をまだ呼び出していない場合、関数 localtime() は、 tzset(3) を使 用して、時刻変換情報を初期化します。

構造体 tm に代入した後、 localtime() は、 tzname の tm_isdst 番めの要素 を、 localtime() の戻り値とともに使用する時間帯短縮形である ASCII 文字列 を指すポインタに設定します。

関数 gmtime() は、同様に時刻の値を変換しますが、時間帯の調整はなく、構造 体 tm を指すポインタを返します (後述)。

ctime() 関数は、 localtime() と同じ方法で現在の時間帯の時刻値を調整し、次 の形式の 26 文字の文字列を指すポインタを返します。

      Thu Nov 24 18:22:48 1986\n\0

フィールドにはすべて一定の幅があります。

ctime_r() は、 ctime() と同じ機能ですが、呼び出し元が結果を保存するために 出力バッファ buf を準備しなければならないという点は異なります。このバッ ファは少なくとも 26 文字の長さである必要があります。 localtime_r() および gmtime_r() は、それぞれ、 localtime() および gmtime() と同じ機能ですが、 呼び出し元が出力バッファ result を準備しなければならないという点は異なり ます。

asctime() 関数は、 *tm が指す構造体 tm 内の細分化された時間を変換し、前述 の例に示した形式にします。

asctime_r() は、 asctime() と同じ機能を備えていますが、呼び出し元が結果を 保存するための出力バッファ buf を準備する点は異なります。このバッファの長 さは少なくとも 26 文字である必要があります。

関数 mktime() と timegm() は、 tm が指す構造体内の細分化した時間を、 time(3) 関数が返す値と同じエンコードの時刻値に変換します (すなわち、基準 時点 UTC からの時刻にします)。 mktime() は、現在の時間帯設定に従って入力 構造体を解釈します ( tzset(3) を参照)。 timegm() は、協定世界時 (UTC) を 表す入力構造体を解釈します。

構造体の tm_wday コンポーネントと tm_yday コンポーネントのオリジナル値は 無視され、他のコンポーネントのオリジナルの値はその通常の範囲に制限されま せんし、必要な場合は正規化されます。例えば、10 月 40 日は 11 月 9 日に変 換され、 tm_hour に −1 が指定されると深夜から 1 時間前を意味し、 tm_mday に 0 が指定されると現在の月の直前の日を意味し、 tm_mon に −2 が指定される と tm_year の 1 月から 2 ヶ月前を意味します。( tm_isdst が 正の場合、 mktime() は、初期的には、指定時間について夏時間 (たとえば、日光節約時間) が有効であると推測します。 0 の場合は、夏時間が有効でないと想定します。 tm_isdst が負の値の場合、 mktime() 関数は、指定の時間について夏時間が有効 であるかどうか推測しようとします。 tm_isdst メンバと tm_gmtoff メンバは timegm() によって強制的に 0 にされます)。

処理が正常に完了すると、構造体の tm_wday コンポーネントおよび tm_yday コ ンポーネントの値は適宜、設定され、他のコンポーネントは指定のカレンダ時間 を表すよう設定されますが、値は通常の範囲にさせられます。 tm_mon と tm_year が決定されるまで、 tm_mday の最終値は設定されません。 mktime() は、指定のカレンダ時間を返します。カレンダ時間が表わせない場合は、−1 が返 されます。

difftime() 関数は、2 つのカレンダ時間の間の差 (time1 - time0) (秒単位) を 返します。

外部宣言と構造体 tm の両方が ⟨time.h⟩ インクルードファイル内にあります。 構造体 tm には少なくとも次のフィールドがインクルードされています。

      int tm_sec;     /∗ 秒 (0 - 60) ∗/

/∗ 分 (0 - 59) ∗/
int tm_hour;

/∗ 時 (0 - 23) ∗/
int tm_mday;

/∗ 月内の日 (1 - 31) ∗/
int tm_mon;

/∗ 月 (0 - 11) ∗/
int tm_year;

/∗ 年 − 1900 ∗/
int tm_wday;

/∗ 曜日 (Sunday = 0) ∗/
int tm_yday;

/∗ 年内の日 (0 - 365) ∗/
int tm_isdst;

/∗ 夏時間は有効か ∗/
char ∗tm_zone;

/∗ 時間帯名の短縮形 ∗/
long tm_gmtoff;

/∗ UTC からのオフセット (秒単位) ∗/

夏時間が有効な場合、フィールド tm_isdst は 0 でなくなります。

フィールド tm_gmtoff は、 UTC から表される時間のオフセット (秒単位) であ り、正の値は本初子午線の東を示します。

date(1), gettimeofday(2), getenv(3), time(3), tzset(3), tzfile(5)

asctime(), ctime(), difftime(), gmtime(), localtime(), mktime() の各関数 は、選択したローカルな時間帯に閏秒テーブルが含まれていない場合だけ、 ISO/IEC 9899:1990 (‘‘ISO C89’’) と ISO/IEC 9945-1:1996 (‘‘POSIX.1’’) に適 合しています ( zic(8) を参照)。

asctime_r(), ctime_r(), gmtime_r(), localtime_r() の各関数は ISO/IEC 9945-1:1996 (‘‘POSIX.1’’) に適合しています (ここでも、選択したローカルな 時間帯に閏秒テーブルが含まれていない場合だけです)。

timegm() 関数は、いかなる規格によっても指定されていません。この関数は、上 述の標準関数を使用しても、完全にはエミュレート不可能です。

このマニュアルページは、 Arthur Olsen によって Berkeley に寄付された時間 パッケージに由来するもので、これは 4.3BSD で登場しました。

difftime(), mktime() および他の関数の _r() のついた変種を除いて、これらの 関数は、結果を内部静的オブジェクトに残し、そのオブジェクトを指すポインタ を返します。後でこれらの関数を呼び出すと、同じオブジェクトが修正されま す。

C 言語規格は、プログラムがその現在のローカル時間帯設定を修正するメカニズ ムを備えていませんし、 POSIX 規格方式は再入可能ではありません (しかし、ス レッドセーフシステムが POSIX スレッド環境には備わっています)。

返された構造体 tm の tm_zone フィールドは、キャラクタの静的配列を指しま す。これも後の呼び出しで上書きされます ( tzset(3) と tzsetwall(3) の後の 呼び出しによって上書きされるのと同じようにです)。

外部変数 tzname の使用はお勧めできません。構造体 tm 内の tm_zone エントリ をお勧めします。

FreeBSD 10.0 January 2, 1999 FreeBSD 10.0