tail head cat sleep
QR code linking to this page

manページ  — CTIME

名称

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

内容

ライブラリ

Standard C Library (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() は、 tznametm_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_montm_year が決定されるまで、 tm_mday の最終値は設定されません。 mktime() は、指定のカレンダ時間を返します。カレンダ時間が表わせない 場合は、-1 が返されます。

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

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

int tm_sec;     /* 秒 (0 - 60) */
int tm_min;     /* 分 (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 C90") と IEEE Std 1003.1-96 ("POSIX.1") に適合しています ( zic(8) を参照)。

asctime_r(), ctime_r(), gmtime_r(), localtime_r() の各関数は IEEE Std 1003.1-96 ("POSIX.1") に適合しています (ここでも、選択したローカルな時間帯に 閏秒テーブルが含まれていない場合だけです)。

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

歴史

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

バグ

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

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

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

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


CTIME (3) January 2, 1999

tail head cat sleep
QR code linking to this page


このマニュアルページサービスについてのご意見は Ben Bullock にお知らせください。 Privacy policy.

Not only is UNIX dead, it's starting to smell really bad.
— Rob Pike