draft/man3/ctime.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" References consulted:
  26 .\"     Linux libc source code
  27 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  28 .\"     386BSD man pages
  29 .\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu)
  30 .\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de)
  31 .\" Modified 2001-11-13, aeb
  32 .\" Modified 2001-12-13, joey, aeb
  33 .\" Modified 2004-11-16, mtk
  34 .\"
  35 .\"*******************************************************************
  36 .\"
  37 .\" This file was generated with po4a. Translate the source file.
  38 .\"
  39 .\"*******************************************************************
  40 .TH CTIME 3 2010\-02\-25 "" "Linux Programmer's Manual"
  41 .SH 名前
  42 asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r,
  43 localtime_r \- 日付と時刻を要素別の時刻や ASCII に変換する
  44 .SH 書式
  45 .nf
  46 \fB#include <time.h>\fP
  47 .sp
  48 \fBchar *asctime(const struct tm *\fP\fItm\fP\fB);\fP
  49 .br
  50 \fBchar *asctime_r(const struct tm *\fP\fItm\fP\fB, char *\fP\fIbuf\fP\fB);\fP
  51 .sp
  52 \fBchar *ctime(const time_t *\fP\fItimep\fP\fB);\fP
  53 .br
  54 \fBchar *ctime_r(const time_t *\fP\fItimep\fP\fB, char *\fP\fIbuf\fP\fB);\fP
  55 .sp
  56 \fBstruct tm *gmtime(const time_t *\fP\fItimep\fP\fB);\fP
  57 .br
  58 \fBstruct tm *gmtime_r(const time_t *\fP\fItimep\fP\fB, struct tm *\fP\fIresult\fP\fB);\fP
  59 .sp
  60 \fBstruct tm *localtime(const time_t *\fP\fItimep\fP\fB);\fP
  61 .br
  62 \fBstruct tm *localtime_r(const time_t *\fP\fItimep\fP\fB, struct tm *\fP\fIresult\fP\fB);\fP
  63 .sp
  64 \fBtime_t mktime(struct tm *\fP\fItm\fP\fB);\fP
  65 .fi
  66 .sp
  67 .in -4n
  68 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  69 .in
  70 .ad l
  71 .sp
  72 \fBasctime_r\fP(), \fBctime_r\fP(), \fBgmtime_r\fP(), \fBlocaltime_r\fP():
  73 .RS
  74 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
  75 || _POSIX_SOURCE
  76 .RE
  77 .ad
  78 .SH 説明
  79 関数 \fBctime\fP(), \fBgmtime\fP(), \fBlocaltime\fP()  は \fItime_t\fP 型のカレンダー時刻を引き数にとる。
  80 引き数が絶対値として解釈される場合は、時刻紀元 (Epoch; 1970\-01\-01 00:00:00 +0000 (UTC))
  81 からの経過秒数と解釈される。
  82 .PP
  83 関数 \fBasctime\fP()  と \fBmktime\fP()  は 年・月・日などに分離された要素別の時刻を引き数とする。
  84 .PP
  85 要素別の時刻は \fI<time.h>\fP で以下のように定義されている \fItm\fP 構造体に保持される。
  86 .sp
  87 .in +4n
  88 .nf
  89 struct tm {
  90     int tm_sec;         /* 秒 */
  91     int tm_min;         /* 分 */
  92     int tm_hour;        /* 時間 */
  93     int tm_mday;        /* 日 */
  94     int tm_mon;         /* 月 */
  95     int tm_year;        /* 年 */
  96     int tm_wday;        /* 曜日 */
  97     int tm_yday;        /* 年内通算日 */
  98     int tm_isdst;       /* 夏時間 */
  99 };
 100 .fi
 101 .in
 102 .PP
 103 \fItm\fP 構造体のメンバーは以下の通り:
 104 .TP  10
 105 \fItm_sec\fP
 106 秒数、ふつうは 0 から 59 までの値、 しかし閏秒のため 60 までの値は許される。
 107 .TP
 108 \fItm_min\fP
 109 分数、0 から 59 までの値。
 110 .TP
 111 \fItm_hour\fP
 112 真夜中からの通算時間、0 から 23 までの値。
 113 .TP
 114 \fItm_mday\fP
 115 月はじめからの日数、1 から 31 までの値。
 116 .TP
 117 \fItm_mon\fP
 118 1月からの通算月数、0 から 11 までの値。
 119 .TP
 120 \fItm_year\fP
 121 1900 年からの通算年数。
 122 .TP
 123 \fItm_wday\fP
 124 日曜日からの通算日数(曜日)。0 から 6 までの値。
 125 .TP
 126 \fItm_yday\fP
 127 1 月 1 日からの通算日数、0 から 365 までの値。
 128 .TP
 129 \fItm_isdst\fP
 130 夏時間が有効かどうかのフラグ。 正の値ならば夏時間は有効になり、0 ならば無効、負の値ならばこの情報には 意味がない。
 131 .PP
 132 \fBctime(\fP\fIt\fP\fB)\fP 関数は、 \fBasctime(localtime(\fP\fIt\fP\fB))\fP と等価である。 カレンダー時刻 \fIt\fP を
 133 .sp
 134 .RS
 135 "Wed Jun 30 21:49:08 1993\en"
 136 .RE
 137 .sp
 138 という形式の NULL 終端された文字列へ変換する。 曜日の略称は "Sun", "Mon", "Tue", "Wed", "Thu", "Fri",
 139 "Sat" である。 月の略称は "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug",
 140 "Sep", "Oct", "Nov", "Dec" である。 返り値は、静的 (static) に割り当てられた文字列へのポインタである。
 141 この文字列は、日付・時刻関数のいずれかが呼び出されると上書きされることがある。 またこの関数は大域変数 \fItzname\fP, \fItimezone\fP,
 142 \fIdaylight\fP に現在のタイムゾーンの情報を設定する (\fBtzset\fP(3)  参照)。 リエントラント版である \fBctime_r\fP()
 143 も同様だが、 文字列はユーザーが用意したバッファに格納される。バッファのサイズは 少なくとも 26 バイト以上でなければならない。 この関数は
 144 \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP を設定する必要はない。
 145 .PP
 146 関数 \fBgmtime\fP()  は、カレンダー時刻 \fItimep\fP を 協定世界時 (UTC) での要素別の時刻へ変換する。
 147 年が整数型に収まらない場合、NULL を返す。 返り値は静的に確保された構造体を指しており、この後で 日付や時刻に関する関数のいずれかが呼び出されると
 148 上書きされる可能性がある。 \fBgmtime_r\fP()  も同様だが、 データはユーザーが用意した構造体に格納される。
 149 .PP
 150 関数 \fBlocaltime\fP()  は、カレンダー時刻 \fItimep\fP を ユーザが指定したタイムゾーンでの時刻要素別の表現へ変換する。 この関数は
 151 \fBtzset\fP(3)  を呼び出したかのように振舞い、 大域変数 \fItzname\fP に現在のタイムゾーンの情報を設定する。
 152 また、\fItimezone\fP に協定世界時 (UTC) とローカル標準時との 時差の秒数を設定し、 一年の一部で夏時間が適用される場合は
 153 \fIdaylight\fP に 0 が設定される。 返り値は静的に確保された構造体を指しており、この後で 日付や時刻に関する関数のいずれかが呼び出されると
 154 上書きされる可能性がある。 \fBlocaltime_r\fP()  も同様だが、 データはユーザーが用意した構造体に格納される。 この関数は
 155 \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP を設定する必要はない。
 156 .PP
 157 関数 \fBasctime\fP()  は、要素別の時刻 \fItm\fP を \fBctime\fP()  と同じ形式の NULL 終端された文字列へ変換する。
 158 返り値は静的に割り当てられた文字列へのポインタである。この文字列は、 日付・時刻関数のいずれかが呼び出されると上書きされることがある。
 159 リエントラント版である \fBasctime_r\fP()  も同様だが、 文字列はユーザーが用意したバッファに格納される。バッファのサイズは 少なくとも
 160 26 バイト以上でなければならない。
 161 .PP
 162 関数 \fBmktime\fP()  は、(ローカルタイムで記述されている) 要素別の時刻を カレンダー時刻へ変換する。この際、呼び出し元がフィールド
 163 \fItm_wday\fP と \fItm_yday\fP で指定した値は無視される。 \fBmktime\fP()  は、フィールド \fItm_isdst\fP
 164 で指定された値により、 \fItm\fP 構造体で渡された時刻で夏時間 (daylight saving time; DST) が有効になって いるかを知る。
 165 正の値は夏時間が有効であることを意味する。 負の値であれば、 \fBmktime\fP()  は (タイムゾーン情報とシステムのデータベースを使って)
 166 指定された時刻で夏時間が有効かどうかを判断する必要があることを意味する。
 167
 168 \fBmktime\fP()  は \fItm\fP 構造体の各フィールドを以下のように修正する。 \fItm_wday\fP と \fItm_yday\fP
 169 には他のフィールドの内容から求めた値を設定する。 構造体の要素が有効な範囲にない場合、正規化される (例えば、10 月 40 日は 11 月 9
 170 日に変更される)。 \fItm_isdst\fP には (最初の値にかかわらず) 正の値か 0 が設定される。
 171 正の値は指定された時間で夏時間が有効であることを示し、 0 は無効であることを示す。 関数 \fBmktime\fP()  を呼び出すと、 大域変数
 172 \fItzname\fP が現在のタイムゾーンに設定される。
 173
 174 要素別の時刻をカレンダー時刻 (紀元 (Epoch) からの秒数) で表現できない場合、 \fBmktime\fP()  は \fI(time_t)\ (\-1)\fP を返し、要素別の時刻の構造体メンバーを変更しない。
 175 .SH 返り値
 176 各関数はそれぞれ前述した値を返す。エラーの場合は NULL (\fBmktime\fP()  では \-1) を返す。
 177 .SH 準拠
 178 POSIX.1\-2001.  C89 と C99 では \fBasctime\fP(), \fBctime\fP(), \fBgmtime\fP(),
 179 \fBlocaltime\fP(), \fBmktime\fP()  が規定されている。 POSIX.1\-2008 は、 \fBasctime\fP(),
 180 \fBasctime_r\fP(), \fBctime\fP(), \fBctime_r\fP()  を廃止予定としている。 代わりに、 \fBstrftime\fP(3)
 181 の使用が推奨されている。
 182 .SH 注意
 183 \fBasctime\fP(), \fBctime\fP(), \fBgmtime\fP(), \fBlocaltime\fP()  の 4
 184 つの関数は静的データへのポインタを返すので、スレッドセーフではない。 これらの関数のスレッドセーフ版である \fBasctime_r\fP(),
 185 \fBctime_r\fP(), \fBgmtime_r\fP(), \fBlocaltime_r\fP()  は SUSv2 で規定されており、 libc 5.2.5
 186 以降で利用できる。
 187
 188 POSIX.1\-2001 では、「関数 \fBasctime\fP(), \fBctime\fP(), \fBgmtime\fP(), \fBlocaltime\fP()
 189 は、要素別の時刻の構造体か \fIchar\fP 型の配列かのどちらかの静的オブジェクトを返すものとする。
 190 これらの関数のいずれかを実行すると、他の関数のどれかがこれらの 静的オブジェクトのどちらかに格納して返した情報が上書きされるかも
 191 しれない。」となっている。 このことは glibc の実装で起こりうる。
 192 .LP
 193 glibc を含む多くの実装では、 \fItm_mday\fP に 0 を指定すると前月の最終日を意味していると解釈される。
 194 .LP
 195 glibc では、 \fI<time.h>\fP がインクルードされる前に \fB_BSD_SOURCE\fP が定義されると、 \fIstruct
 196 tm\fP に以下のフィールドが追加される。
 197 .sp
 198 .RS
 199 .nf
 200 long tm_gmtoff;           /* Seconds east of UTC */
 201 const char *tm_zone;      /* Timezone abbreviation */
 202 .fi
 203 .RE
 204 .sp
 205 これは BSD 拡張であり、4.3BSD\-Reno から現れた。
 206
 207 .\" See http://thread.gmane.org/gmane.comp.time.tz/2034/
 208 POSIX.1\-2004 によると、 \fBlocaltime\fP()  はあたかも \fBtzset\fP(3)
 209 が呼ばれたかのように振舞うことが要求されているが、 \fBlocaltime_r\fP()  にはこの要件はない。 移植性が必要なコードでは、
 210 \fBlocaltime_r\fP()  の前に \fBtzset\fP(3)  を呼び出しておくべきである。
 211 .SH 関連項目
 212 \fBdate\fP(1), \fBgettimeofday\fP(2), \fBtime\fP(2), \fButime\fP(2), \fBclock\fP(3),
 213 \fBdifftime\fP(3), \fBstrftime\fP(3), \fBstrptime\fP(3), \fBtimegm\fP(3), \fBtzset\fP(3),
 214 \fBtime\fP(7)
 215 .SH この文書について
 216 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 217 である。プロジェクトの説明とバグ報告に関する情報は
 218 http://www.kernel.org/doc/man\-pages/ に書かれている。