Provided by: manpages-ja-dev_0.5.0.0.20210215+dfsg-1_all 
名前
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() は、要素別の時刻 tm を ctime() と同じ形式のヌル終端された文字列へ変換する。 返り値は静的
に割り当てられた文字列へのポインターである。この文字列は、 日付・時刻関数のいずれかが呼び出されると上書き
されることがある。 リエントラント版である asctime_r() も同様だが、 文字列はユーザーが用意したバッファー
に格納される。バッファーのサイズは 少なくとも 26 バイト以上でなければならない。
関数 mktime() は、(ローカルタイムで記述されている) 要素別の時刻を カレンダー時刻へ変換する。この際、呼び
出し元がフィールド tm_wday と tm_yday で指定した値は無視される。 mktime() は、フィールド tm_isdst で指定
された値により、 tm 構造体で渡された時刻で夏時間 (daylight saving time; DST) が有効になって いるかを知
る。 正の値は夏時間が有効であることを意味する。 負の値であれば、 mktime() は (タイムゾーン情報とシステム
のデータベースを使って) 指定された時刻で夏時間が有効かどうかを判断する必要があることを意味する。
mktime() は tm 構造体の各フィールドを以下のように修正する。 tm_wday と tm_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/ に書かれている。
2014-08-19 CTIME(3)