ctime - ライブラリコールの説明 - Linux コマンド集一覧表

名前
書式
説明
返り値
注意
準拠
関連項目

名前

asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, localtime_r - 日付と時刻を要素別の時刻や ASCII に変換する

書式

#include <time.h>


char *asctime(const struct tm *tm);


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


char *ctime(const time_t *timep);


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


struct tm *gmtime(const time_t *timep);


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


struct tm *localtime(const time_t *timep);


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


time_t mktime(struct tm *tm);

説明

関数 ctime (), gmtime (), localtime () は time_t 型のカレンダー時刻を引き数にとる。引き数は、協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 からの経過秒数と解釈される。

関数 asctime () と mktime () は年・月・日などに分離された要素別の時刻を引き数とする。

要素別の時刻は <time.h> で以下のように定義されている tm 構造体に保持される。

struct tm {
    int tm_sec;         /* 秒 */
    int tm_min;         /* 分 */
    int tm_hour;        /* 時間 */
    int tm_mday;        /* 日 */
    int tm_mon;         /* 月 */
    int tm_year;        /* 年 */
    int tm_wday;        /* 曜日 */
    int tm_yday;        /* 年内通算日 */
    int tm_isdst;       /* 夏時間 */
};

tm 構造体のメンバーは以下の通り:

tm_sec

秒数、ふつうは 0 から 59 までの値、しかし閏秒のため 60 までの値は許される。

tm_min

分数、0 から 59 までの値。

tm_hour

真夜中からの通算時間、0 から 23 までの値。

tm_mday

月はじめからの日数、1 から 31 までの値。

tm_mon

1月からの通算月数、0 から 11 までの値。

tm_year

1900 年からの通算年数。

tm_wday

日曜日からの通算日数(曜日)。0 から 6 までの値。

tm_yday

1 月 1 日からの通算日数、0 から 365 までの値。

tm_isdst

夏時間が有効かどうかのフラグ。正の値ならば夏時間は有効になり、0 ならば無効、負の値ならばこの情報には意味がない。

ctime( t ) 関数は、 asctime(localtime( t )) と等価である。カレンダー時刻 t を

"Wed Jun 30 21:49:08 1993\n"

という形式の文字列へ変換する。曜日の略称は `Sun', `Mon', `Tue', `Wed', `Thu', `Fri', `Sat' である。月の略称は `Jan', `Feb', `Mar', `Apr', `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', `Dec' である。返り値は、静的 (static) に割り当てられた文字列へのポインタである。この文字列は、日付・時刻関数のいずれかが呼び出されると上書きされることがある。またこの関数は大域変数 tzname に現在のタイムゾーンの情報を設定する ( tzset (3)参照)。リエントラント版である ctime_r () も同様だが、文字列はユーザーが用意したバッファに格納される。バッファのサイズは少なくとも 26 文字以上でなければならない。この関数は tzname を設定する必要はない。

関数 gmtime () は、カレンダー時刻 timep を協定世界時 (UTC) での要素別の時刻へ変換する。年が整数型に収まらない場合、NULL を返す。返り値は静的に確保された構造体を指しており、この後で日付や時刻に関する関数のいずれかが呼び出されると上書きされる可能性がある。 gmtime_r () も同様だが、データはユーザーが用意した構造体に格納される。

関数 localtime () は、ユーザが指定したタイムゾーンでの時刻要素へ変換する。この関数は tzset (3) を呼び出したかのように振舞い、大域変数 tzname に現在のタイムゾーンの情報を設定する。また、timezone に協定世界時 (UTC) とローカル標準時との時差の秒数を設定し、一年の一部で夏時間が適用される場合は daylight に 0 が設定される。返り値は静的に確保された構造体を指しており、この後で日付や時刻に関する関数のいずれかが呼び出されると上書きされる可能性がある。 localtime_r () も同様だが、データはユーザーが用意した構造体に格納される。 tzname を設定する必要はない。

関数 asctime () は、要素別の時刻 tm を ctime () と同じ形式の文字列へ変換する。返り値は静的に割り当てられた文字列へのポインタである。この文字列は、日付・時刻関数のいずれかが呼び出されると上書きされることがある。リエントラント版である asctime_r () も同様だが、文字列はユーザーが用意したバッファに格納される。バッファのサイズは少なくとも 26 文字以上でなければならない。

関数 mktime () は、(ローカルタイムで記述されている) 要素別の時刻をカレンダー時刻へ変換する。この関数は時刻要素のうち tm_wday と tm_yday の値は無視し、他の時刻要素からそれらの値を再計算する。構造体の要素がその正しい範囲にない場合、正規化される (つまり、10 月 40 日は 11 月 9 日に変更される)。関数 mktime () を呼び出すと、大域変数 tzname が現在のタイムゾーンに設定される。要素別の時刻をカレンダー時刻 (紀元からの秒数) で表現できない場合、 mktime () は (time_t)(-1) を返し、時刻要素 tm_wday と tm_yday は変更しない。

返り値

各関数はそれぞれ前述した値を返す。エラーの場合は NULL (mktime () では -1) を返す。

注意

asctime (), ctime (), gmtime (), localtime ()の 4 つの関数は静的データへのポインタを返すので、スレッドセーフではない。これらの関数のスレッドセーフ版である asctime_r (), ctime_r (), gmtime_r (), localtime_r ()は SUSv2 で規定されており、 libc 5.2.5 以降で利用できる。

glibc を含む多くの実装では、 tm_mday に 0 を指定すると前月の最終日を意味していると解釈される。

glibc では、 <time.h> がインクルードされる前に _BSD_SOURCE が定義されると、 struct tm に以下のフィールドが追加される。

long tm_gmtoff;           /* Seconds east of UTC */
const char *tm_zone;      /* Timezone abbreviation */

これは BSD 拡張であり、4.3BSD-Reno から現れた。

準拠

SVr4, POSIX.1-2001, 4.3BSD, C89, C99.

ctime - ライブラリコールの説明 - Linux コマンド集 一覧表

名前

書式

説明

返り値

注意

準拠

関連項目

ctime - ライブラリコールの説明 - Linux コマンド集一覧表