Manpages

名 前

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);

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

asctime_r(), ctime_r(), gmtime_r(), localtime_r():

_POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE || _POSIX_SOURCE

説 明

関 数 ctime(), gmtime(), localtime() は time_t 型 の カ レ ン ダ ー 時 刻 を 引 き 数 に と る 。 引 き 数 が 絶 対 値 と し て 解 釈 さ れ る 場 合 は 、 時 刻 紀 元 (Epoch; 1970−01−01 00:00:00 +0000 (UTC)) か ら の 経 過 秒 数 と 解 釈 さ れ る 。 関 数 asctime() と mktime() は 年 ・ 月 ・ 日 な ど に 分 離 さ れ た 要 素 別 の 時 刻 を 引 き 数 と す る 。 要 素 別 の 時 刻 は <time.h> で 以 下 の よ う に 定 義 さ れ て い る tm 構 造 体 に 保 持 さ れ る 。

struct 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; /* 曜 日 (0−6, 日 曜 = 0) */
int tm_yday; /* 年 内 通 算 日 (0−365, 1 月 1 日 = 0) */
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, timezone, daylight に 現 在 の タ イ ム ゾ ー ン の 情 報 を 設 定 す る (tzset(3) 参 照 )。 リ エ ン ト ラ ン ト 版 で あ る ctime_r() も 同 様 だ が 、 文 字 列 は ユ ー ザ ー が 用 意 し た バ ッ フ ァ ー に 格 納 さ れ る 。 バ ッ フ ァ ー の サ イ ズ は 少 な く と も 26 バ イ ト 以 上 で な け れ ば な ら な い 。 こ の 関 数 は tzname, timezone, and daylight を 設 定 す る 必 要 は な い 。 関 数 gmtime() は 、 カ レ ン ダ ー 時 刻 timep を 協 定 世 界 時 (UTC) で の 要 素 別 の 時 刻 へ 変 換 す る 。 年 が 整 数 型 に 収 ま ら な い 場 合 、 NULL を 返 す 。 返 り 値 は 静 的 に 確 保 さ れ た 構 造 体 を 指 し て お り 、 こ の 後 で 日 付 や 時 刻 に 関 す る 関 数 の い ず れ か が 呼 び 出 さ れ る と 上 書 き さ れ る 可 能 性 が あ る 。 gmtime_r() も 同 様 だ が 、 デ ー タ は ユ ー ザ ー が 用 意 し た 構 造 体 に 格 納 さ れ る 。 関 数 localtime() は 、 カ レ ン ダ ー 時 刻 timep を ユ ー ザ ー が 指 定 し た タ イ ム ゾ ー ン で の 時 刻 要 素 別 の 表 現 へ 変 換 す る 。 こ の 関 数 は tzset(3) を 呼 び 出 し た か の よ う に 振 舞 い 、 大 域 変 数 tzname に 現 在 の タ イ ム ゾ ー ン の 情 報 を 設 定 す る 。 ま た 、 timezone に 協 定 世 界 時 (UTC) と ロ ー カ ル 標 準 時 と の 時 差 の 秒 数 を 設 定 し 、 一 年 の 一 部 で 夏 時 間 が 適 用 さ れ る 場 合 は daylight に 0 が 設 定 さ れ る 。 返 り 値 は 静 的 に 確 保 さ れ た 構 造 体 を 指 し て お り 、 こ の 後 で 日 付 や 時 刻 に 関 す る 関 数 の い ず れ か が 呼 び 出 さ れ る と 上 書 き さ れ る 可 能 性 が あ る 。 localtime_r() も 同 様 だ が 、 デ ー タ は ユ ー ザ ー が 用 意 し た 構 造 体 に 格 納 さ れ る 。 こ の 関 数 は tzname, timezone, and daylight を 設 定 す る 必 要 は な い 。 関 数 asctime() は 、 要 素 別 の 時 刻 tmctime() と 同 じ 形 式 の ヌ ル 終 端 さ れ た 文 字 列 へ 変 換 す る 。 返 り 値 は 静 的 に 割 り 当 て ら れ た 文 字 列 へ の ポ イ ン タ ー で あ る 。 こ の 文 字 列 は 、 日 付 ・ 時 刻 関 数 の い ず れ か が 呼 び 出 さ れ る と 上 書 き さ れ る こ と が あ る 。 リ エ ン ト ラ ン ト 版 で あ る asctime_r() も 同 様 だ が 、 文 字 列 は ユ ー ザ ー が 用 意 し た バ ッ フ ァ ー に 格 納 さ れ る 。 バ ッ フ ァ ー の サ イ ズ は 少 な く と も 26 バ イ ト 以 上 で な け れ ば な ら な い 。 関 数 mktime() は 、 (ロ ー カ ル タ イ ム で 記 述 さ れ て い る ) 要 素 別 の 時 刻 を カ レ ン ダ ー 時 刻 へ 変 換 す る 。 こ の 際 、 呼 び 出 し 元 が フ ィ ー ル ド tm_wdaytm_yday で 指 定 し た 値 は 無 視 さ れ る 。 mktime() は 、 フ ィ ー ル ド tm_isdst で 指 定 さ れ た 値 に よ り 、 tm 構 造 体 で 渡 さ れ た 時 刻 で 夏 時 間 (daylight saving time; DST) が 有 効 に な っ て い る か を 知 る 。 正 の 値 は 夏 時 間 が 有 効 で あ る こ と を 意 味 す る 。 負 の 値 で あ れ ば 、 mktime() は (タ イ ム ゾ ー ン 情 報 と シ ス テ ム の デ ー タ ベ ー ス を 使 っ て ) 指 定 さ れ た 時 刻 で 夏 時 間 が 有 効 か ど う か を 判 断 す る 必 要 が あ る こ と を 意 味 す る 。

mktime() は tm 構 造 体 の 各 フ ィ ー ル ド を 以 下 の よ う に 修 正 す る 。 tm_wdaytm_yday に は 他 の フ ィ ー ル ド の 内 容 か ら 求 め た 値 を 設 定 す る 。 構 造 体 の 要 素 が 有 効 な 範 囲 に な い 場 合 、 正 規 化 さ れ る (例 え ば 、 10 月 40 日 は 11 月 9 日 に 変 更 さ れ る )。 tm_isdst に は (最 初 の 値 に か か わ ら ず ) 正 の 値 か 0 が 設 定 さ れ る 。 正 の 値 は 指 定 さ れ た 時 間 で 夏 時 間 が 有 効 で あ る こ と を 示 し 、 0 は 無 効 で あ る こ と を 示 す 。 関 数 mktime() を 呼 び 出 す と 、 大 域 変 数 tzname が 現 在 の タ イ ム ゾ ー ン に 設 定 さ れ る 。 要 素 別 の 時 刻 を カ レ ン ダ ー 時 刻 (紀 元 (Epoch) か ら の 秒 数 ) で 表 現 で き な い 場 合 、 mktime() は (time_t) (−1) を 返 し 、 要 素 別 の 時 刻 の 構 造 体 メ ン バ ー を 変 更 し な い 。

返 り 値

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

準 拠

POSIX.1−2001. C89 と C99 で は asctime(), ctime(), gmtime(), localtime(), mktime() が 規 定 さ れ て い る 。 POSIX.1−2008 は 、 asctime(), asctime_r(), ctime(), ctime_r() を 廃 止 予 定 と し て い る 。 代 わ り に 、 strftime(3) の 使 用 が 推 奨 さ れ て い る 。

注 意

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

POSIX.1−2001 で は 、 「 関 数 asctime(), ctime(), gmtime(), localtime() は 、 要 素 別 の 時 刻 の 構 造 体 か char 型 の 配 列 か の ど ち ら か の 静 的 オ ブ ジ ェ ク ト を 返 す も の と す る 。 こ れ ら の 関 数 の い ず れ か を 実 行 す る と 、 他 の 関 数 の ど れ か が こ れ ら の 静 的 オ ブ ジ ェ ク ト の ど ち ら か に 格 納 し て 返 し た 情 報 が 上 書 き さ れ る か も し れ な い 。 」 と な っ て い る 。 こ の こ と は glibc の 実 装 で 起 こ り う る 。

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 か ら 現 れ た 。

POSIX.1−2004 に よ る と 、 localtime() は あ た か も tzset(3) が 呼 ば れ た か の よ う に 振 舞 う こ と が 要 求 さ れ て い る が 、 localtime_r() に は こ の 要 件 は な い 。 移 植 性 が 必 要 な コ ー ド で は 、 localtime_r() の 前 に tzset(3) を 呼 び 出 し て お く べ き で あ る 。

関 連 項 目

date(1), gettimeofday(2), time(2), utime(2), clock(3), difftime(3), strftime(3), strptime(3), timegm(3), tzset(3), time(7)

こ の 文 書 に つ い て

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

COMMENTS