CTIME

Section: Linux Programmer's Manual (3)
Updated: 2007-07-26
Index JM Home Page roff page
 

名前

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 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE  

説明

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

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

返り値

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

準拠

POSIX.1-2001. C89 と C99 では asctime(), ctime(), gmtime(), localtime(), mktime() が規定されている。  

注意

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

関連項目

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


 

Index

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

This document was created by man2html, using the manual pages.
Time: 04:31:36 GMT, November 19, 2007