ctimeのヘルプ・マニュアル
日本語 英語
ctime --help
man ctime
CTIME(3) Linux Programmer’s Manual CTIME(3)
名前
asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r,
gmtime_r, localtime_r - 日付と時刻を要素別の時刻や ASCII に変換する
書式
#include
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 型のカレンダー時刻を引き
数にとる。引き数は、協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から の
経過秒数と解釈される。
関数 asctime() と mktime() は年・月・日などに分離された要素別の時刻を引
き数とする。
要素別の時刻は で以下のように定義されている 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"
という形式の NULL 終端された文字列へ変換する。曜 日 の 略 称 は "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() は、ユーザが指定したタイムゾーンでの時刻要素へ変換する
。この関数は tzset(3) を呼び出したかのように振舞い、大域変数 tzname に
現 在 のタイムゾーンの情報を設定する。また、timezone に協定世界時 (UTC)
とローカル標準時との時差の秒数を設定し、一年の一部で夏時間が適用され る
場合は daylight に 0 が設定される。返り値は静的に確保された構造体を指し
ており、この後で日付や時刻に関する関数のいずれかが呼び出されると上書 き
される可能性がある。 localtime_r() も同様だが、データはユーザーが用意し
た構造体に格納される。この関数は tzname, timezone, and daylight を設 定
する必要はない。
関 数 asctime() は、要素別の時刻 tm を ctime() と同じ形式の NULL 終端さ
れた文字列へ変換する。返り値は静的に割り当てられた文字列へのポインタ で
あ る。この文字列は、日付・時刻関数のいずれかが呼び出されると上書きされ
ることがある。リエントラント版である 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(), local-
time(), mktime() が規定されている。 POSIX.1-2008 は、 asctime(), asc-
time_r(), ctime(), ctime_r() を廃止予定としている。代わ り に 、 strf-
time(3) の使用が推奨されている。
注意
asctime(), ctime(), gmtime(), localtime() の 4 つの関数は静的データへの
ポインタを返すので、スレッドセーフではない。これらの関数のスレッドセ ー
フ 版 である asctime_r(), ctime_r(), gmtime_r(), localtime_r() は SUSv2
で規定されており、 libc 5.2.5 以降で利用できる。
POSIX.1-2001 では、「関数 asctime(), ctime(), gmtime(), localtime() は
、 要素別の時刻の構造体か char 型の配列かのどちらかの静的オブジェクトを
返すものとする。これらの関数のいずれかを実行すると、他の関数のどれか が
こ れらの静的オブジェクトのどちらかに格納して返した情報が上書きされるか
もしれない。」となっている。このことは glibc の実装で起こりうる。
glibc を含む多くの実装では、 tm_mday に 0 を指定すると前月の最終日を 意
味していると解釈される。
glibc では、 がインクルードされる前に _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() が呼ばれたかのよ
うに振舞うことが要求されているが、 localtime_r() にはこの要件はない。移
植性が必要なコードでは、 localtime_r() の前に tzset() を呼び出してお く
べきである。
関連項目
date(1), gettimeofday(2), time(2), utime(2), clock(3), difftime(3),
strftime(3), strptime(3), timegm(3), tzset(3), time(7)
2009-03-15 CTIME(3)
CTIME(3) Linux Programmer’s Manual CTIME(3)
NAME
asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r,
gmtime_r, localtime_r - transform date and time to broken-down time or
ASCII
SYNOPSIS
#include
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);
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
asctime_r(), ctime_r(), gmtime_r(), localtime_r():
_POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE ||
_POSIX_SOURCE
DESCRIPTION
The ctime(), gmtime() and localtime() functions all take an argument of
data type time_t which represents calendar time. When interpreted as
an absolute time value, it represents the number of seconds elapsed
since 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC).
The asctime() and mktime() functions both take an argument representing
broken-down time which is a representation separated into year, month,
day, etc.
Broken-down time is stored in the structure tm which is defined in
as follows:
struct tm {
int tm_sec; /* seconds */
int tm_min; /* minutes */
int tm_hour; /* hours */
int tm_mday; /* day of the month */
int tm_mon; /* month */
int tm_year; /* year */
int tm_wday; /* day of the week */
int tm_yday; /* day in the year */
int tm_isdst; /* daylight saving time */
};
The members of the tm structure are:
tm_sec The number of seconds after the minute, normally in the range
0 to 59, but can be up to 60 to allow for leap seconds.
tm_min The number of minutes after the hour, in the range 0 to 59.
tm_hour The number of hours past midnight, in the range 0 to 23.
tm_mday The day of the month, in the range 1 to 31.
tm_mon The number of months since January, in the range 0 to 11.
tm_year The number of years since 1900.
tm_wday The number of days since Sunday, in the range 0 to 6.
tm_yday The number of days since January 1, in the range 0 to 365.
tm_isdst A flag that indicates whether daylight saving time is in
effect at the time described. The value is positive if day-
light saving time is in effect, zero if it is not, and nega-
tive if the information is not available.
The call ctime(t) is equivalent to asctime(localtime(t)). It converts
the calendar time t into a null-terminated string of the form
"Wed Jun 30 21:49:08 1993\n"
The abbreviations for the days of the week are "Sun", "Mon", "Tue",
"Wed", "Thu", "Fri", and "Sat". The abbreviations for the months are
"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct",
"Nov", and "Dec". The return value points to a statically allocated
string which might be overwritten by subsequent calls to any of the
date and time functions. The function also sets the external variables
tzname, timezone, and daylight (see tzset(3)) with information about
the current timezone. The reentrant version ctime_r() does the same,
but stores the string in a user-supplied buffer which should have room
for at least 26 bytes. It need not set tzname, timezone, and daylight.
The gmtime() function converts the calendar time timep to broken-down
time representation, expressed in Coordinated Universal Time (UTC). It
may return NULL when the year does not fit into an integer. The return
value points to a statically allocated struct which might be overwrit-
ten by subsequent calls to any of the date and time functions. The
gmtime_r() function does the same, but stores the data in a user-sup-
plied struct.
The localtime() function converts the calendar time timep to broken-
time representation, expressed relative to the user’s specified time-
zone. The function acts as if it called tzset(3) and sets the external
variables tzname with information about the current timezone, timezone
with the difference between Coordinated Universal Time (UTC) and local
standard time in seconds, and daylight to a non-zero value if daylight
savings time rules apply during some part of the year. The return
value points to a statically allocated struct which might be overwrit-
ten by subsequent calls to any of the date and time functions. The
localtime_r() function does the same, but stores the data in a user-
supplied struct. It need not set tzname, timezone, and daylight.
The asctime() function converts the broken-down time value tm into a
null-terminated string with the same format as ctime(). The return
value points to a statically allocated string which might be overwrit-
ten by subsequent calls to any of the date and time functions. The
asctime_r() function does the same, but stores the string in a user-
supplied buffer which should have room for at least 26 bytes.
The mktime() function converts a broken-down time structure, expressed
as local time, to calendar time representation. The function ignores
the values supplied by the caller in the tm_wday and tm_yday fields.
The value specified in the tm_isdst field informs mktime() whether or
not daylight saving time (DST) is in effect for the time supplied in
the tm structure: a positive value means DST is in effect; zero means
that DST is not in effect; and a negative value means that mktime()
should (use timezone information and system databases to) attempt to
determine whether DST is in effect at the specified time.
The mktime() function modifies the fields of the tm structure as fol-
lows: tm_wday and tm_yday are set to values determined from the con-
tents of the other fields; if structure members are outside their valid
interval, they will be normalized (so that, for example, 40 October is
changed into 9 November); tm_isdst is set (regardless of its initial
value) to a positive value or to 0, respectively, to indicate whether
DST is or is not in effect at the specified time. Calling mktime()
also sets the external variable tzname with information about the cur-
rent timezone.
If the specified broken-down time cannot be represented as calendar
time (seconds since the Epoch), mktime() returns a value of (time_t) -1
and does not alter the members of the broken-down time structure.
RETURN VALUE
Each of these functions returns the value described, or NULL (-1 in
case of mktime()) in case an error was detected.
CONFORMING TO
POSIX.1-2001. C89 and C99 specify asctime(), ctime(), gmtime(), local-
time(), and mktime(). POSIX.1-2008 marks asctime(), asctime_r(),
ctime(), and ctime_r() as obsolete, recommending the use of strftime(3)
instead.
NOTES
The four functions asctime(), ctime(), gmtime() and localtime() return
a pointer to static data and hence are not thread-safe. Thread-safe
versions asctime_r(), ctime_r(), gmtime_r() and localtime_r() are spec-
ified by SUSv2, and available since libc 5.2.5.
POSIX.1-2001 says: "The asctime(), ctime(), gmtime(), and localtime()
functions shall return values in one of two static objects: a broken-
down time structure and an array of type char. Execution of any of the
functions may overwrite the information returned in either of these
objects by any of the other functions." This can occur in the glibc
implementation.
In many implementations, including glibc, a 0 in tm_mday is interpreted
as meaning the last day of the preceding month.
The glibc version of struct tm has additional fields
long tm_gmtoff; /* Seconds east of UTC */
const char *tm_zone; /* Timezone abbreviation */
defined when _BSD_SOURCE was set before including . This is a
BSD extension, present in 4.3BSD-Reno.
According to POSIX.1-2004, localtime() is required to behave as though
tzset() was called, while localtime_r() does not have this requirement.
For portable code tzset() should be called before localtime_r().
SEE ALSO
date(1), gettimeofday(2), time(2), utime(2), clock(3), difftime(3),
strftime(3), strptime(3), timegm(3), tzset(3), time(7)
COLOPHON
This page is part of release 3.22 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
2009-03-15 CTIME(3)