Provided by: manpages-ja-dev_0.5.0.0.20221215+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
|| /* glibc 2.19 以前: */ _BSD_SOURCE || _SVID_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) を返し、要素別の時刻の構造体メンバーを変更しない。
返り値
On success, gmtime() and localtime() return a pointer to a struct tm.
On success, gmtime_r() and localtime_r() return the address of the structure pointed to
by result.
On success, asctime() and ctime() return a pointer to a string.
On success, asctime_r() and ctime_r() return a pointer to the string pointed to by buf.
On success, mktime() returns the calendar time (seconds since the Epoch), expressed as a
value of type time_t.
On error, mktime() returns the value (time_t) -1. The remaining functions return NULL on
error. On error, errno is set to indicate the cause of the error.
エラー
EOVERFLOW
The result cannot be represented.
属性
この節で使用されている用語の説明については、 attributes(7) を参照。
┌─────────────────┬───────────────┬─────────────────────────────────┐
│インターフェース │ 属性 │ 値 │
├─────────────────┼───────────────┼─────────────────────────────────┤
│asctime() │ Thread safety │ MT-Unsafe race:asctime locale │
├─────────────────┼───────────────┼─────────────────────────────────┤
│asctime_r() │ Thread safety │ MT-Safe locale │
├─────────────────┼───────────────┼─────────────────────────────────┤
│ctime() │ Thread safety │ MT-Unsafe race:tmbuf │
│ │ │ race:asctime env locale │
├─────────────────┼───────────────┼─────────────────────────────────┤
│ctime_r(), │ Thread safety │ MT-Safe env locale │
│gmtime_r(), │ │ │
│localtime_r(), │ │ │
│mktime() │ │ │
├─────────────────┼───────────────┼─────────────────────────────────┤
│gmtime(), │ Thread safety │ MT-Unsafe race:tmbuf env locale │
│localtime() │ │ │
└─────────────────┴───────────────┴─────────────────────────────────┘
準拠
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 に以
下のフィールドが追加される。
const char *tm_zone; /* Timezone abbreviation */
これは BSD 拡張であり、4.3BSD-Reno から現れた。
POSIX.1-2001 によると、 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 プロジェクトのリリース 5.10 の一部である。プロジェクトの
説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。
2020-12-21 CTIME(3)