#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 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
関数 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 構造体のメンバーは以下の通り:
ctime(t) 関数は、 asctime(localtime(t)) と等価である。 カレンダー時刻 t を
という形式の文字列へ変換する。 曜日の略称は `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 は変更しない。
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 から現れた。