release/man3/ctime.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" References consulted:
  24 .\"     Linux libc source code
  25 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  26 .\"     386BSD man pages
  27 .\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu)
  28 .\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de)
  29 .\" Modified 2001-11-13, aeb
  30 .\" Modified 2004-11-16, mtk
  31 .\"
  32 .\" Japanese Version Copyright (c) 1997 Hiroaki Nagoya
  33 .\"         all rights reserved.
  34 .\" Translated 1997-02-10, Hiroaki Nagoya <nagoya@is.titech.ac.jp>
  35 .\" Updated 1999-09-01, Kentaro Shirakata <argrath@ub32.org>
  36 .\" Updated 2001-10-15, Kentaro Shirakata <argrath@ub32.org>
  37 .\" Updated 2001-12-13, Kentaro Shirakata <argrath@ub32.org>
  38 .\" Updated 2002-01-03, Kentaro Shirakata <argrath@ub32.org>
  39 .\" Updated 2005-02-24, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  40 .\" Updated 2008-04-04, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.79
  41 .\" Updated 2008-08-08, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.05
  42 .\" Updated 2008-11-10, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.13
  43 .\"
  44 .\"WORD: Coordinated Univarsal Time  協定世界時
  45 .\"WORD: broken-down time  要素別の時刻
  46 .\"
  47 .TH CTIME 3 2010-02-25 "" "Linux Programmer's Manual"
  48 .SH 名前
  49 asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r,
  50 localtime_r \- 日付と時刻を要素別の時刻や ASCII に変換する
  51 .SH 書式
  52 .nf
  53 .B #include <time.h>
  54 .sp
  55 .BI "char *asctime(const struct tm *" tm );
  56 .br
  57 .BI "char *asctime_r(const struct tm *" tm ", char *" buf );
  58 .sp
  59 .BI "char *ctime(const time_t *" timep );
  60 .br
  61 .BI "char *ctime_r(const time_t *" timep ", char *" buf );
  62 .sp
  63 .BI "struct tm *gmtime(const time_t *" timep );
  64 .br
  65 .BI "struct tm *gmtime_r(const time_t *" timep ", struct tm *" result );
  66 .sp
  67 .BI "struct tm *localtime(const time_t *" timep );
  68 .br
  69 .BI "struct tm *localtime_r(const time_t *" timep ", struct tm *" result );
  70 .sp
  71 .BI "time_t mktime(struct tm *" tm );
  72 .fi
  73 .sp
  74 .in -4n
  75 glibc 向けの機能検査マクロの要件
  76 .RB ( feature_test_macros (7)
  77 参照):
  78 .in
  79 .ad l
  80 .sp
  81 .BR asctime_r (),
  82 .BR ctime_r (),
  83 .BR gmtime_r (),
  84 .BR localtime_r ():
  85 .RS
  86 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE ||
  87 _SVID_SOURCE || _POSIX_SOURCE
  88 .RE
  89 .ad
  90 .SH 説明
  91 関数
  92 .BR ctime (),
  93 .BR gmtime (),
  94 .BR localtime ()
  95 は
  96 \fItime_t\fP 型のカレンダー時刻を引き数にとる。
  97 引き数が絶対値として解釈される場合は、時刻紀元 (Epoch;
  98 1970-01-01 00:00:00 +0000 (UTC)) からの経過秒数と解釈される。
  99 .PP
 100 関数
 101 .BR asctime ()
 102 と
 103 .BR mktime ()
 104 は
 105 年・月・日などに分離された要素別の時刻を引き数とする。
 106 .PP
 107 要素別の時刻は \fI<time.h>\fP で以下のように定義されている
 108 \fItm\fP 構造体に保持される。
 109 .sp
 110 .in +4n
 111 .nf
 112 struct tm {
 113     int tm_sec;         /* 秒 */
 114     int tm_min;         /* 分 */
 115     int tm_hour;        /* 時間 */
 116     int tm_mday;        /* 日 */
 117     int tm_mon;         /* 月 */
 118     int tm_year;        /* 年 */
 119     int tm_wday;        /* 曜日 */
 120     int tm_yday;        /* 年内通算日 */
 121     int tm_isdst;       /* 夏時間 */
 122 };
 123 .fi
 124 .in
 125 .PP
 126 \fItm\fP 構造体のメンバーは以下の通り:
 127 .TP 10
 128 .I tm_sec
 129 秒数、ふつうは 0 から 59 までの値、
 130 しかし閏秒のため 60 までの値は許される。
 131 .TP
 132 .I tm_min
 133 分数、0 から 59 までの値。
 134 .TP
 135 .I tm_hour
 136 真夜中からの通算時間、0 から 23 までの値。
 137 .TP
 138 .I tm_mday
 139 月はじめからの日数、1 から 31 までの値。
 140 .TP
 141 .I tm_mon
 142 1月からの通算月数、0 から 11 までの値。
 143 .TP
 144 .I tm_year
 145 1900 年からの通算年数。
 146 .TP
 147 .I tm_wday
 148 日曜日からの通算日数(曜日)。0 から 6 までの値。
 149 .TP
 150 .I tm_yday
 151 1 月 1 日からの通算日数、0 から 365 までの値。
 152 .TP
 153 .I tm_isdst
 154 夏時間が有効かどうかのフラグ。
 155 正の値ならば夏時間は有効になり、0 ならば無効、負の値ならばこの情報には
 156 意味がない。
 157 .PP
 158 .BI ctime( t )
 159 関数は、
 160 .BI asctime(localtime( t ))
 161 と等価である。
 162 カレンダー時刻 \fIt\fP を
 163 .sp
 164 .RS
 165 "Wed Jun 30 21:49:08 1993\\n"
 166 .RE
 167 .sp
 168 という形式の NULL 終端された文字列へ変換する。
 169 曜日の略称は
 170 "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" である。
 171 月の略称は "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug",
 172 "Sep", "Oct", "Nov", "Dec" である。
 173 返り値は、静的 (static) に割り当てられた文字列へのポインタである。
 174 この文字列は、日付・時刻関数のいずれかが呼び出されると上書きされることがある。
 175 またこの関数は大域変数 \fItzname\fP, \fItimezone\fP, \fIdaylight\fP
 176 に現在のタイムゾーンの情報を設定する
 177 .RB ( tzset (3)
 178 参照)。
 179 リエントラント版である
 180 .BR ctime_r ()
 181 も同様だが、
 182 文字列はユーザーが用意したバッファに格納される。バッファのサイズは
 183 少なくとも 26 バイト以上でなければならない。
 184 この関数は \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP
 185 を設定する必要はない。
 186 .PP
 187 関数
 188 .BR gmtime ()
 189 は、カレンダー時刻 \fItimep\fP を
 190 協定世界時 (UTC) での要素別の時刻へ変換する。
 191 年が整数型に収まらない場合、NULL を返す。
 192 返り値は静的に確保された構造体を指しており、この後で
 193 日付や時刻に関する関数のいずれかが呼び出されると
 194 上書きされる可能性がある。
 195 .BR gmtime_r ()
 196 も同様だが、
 197 データはユーザーが用意した構造体に格納される。
 198 .PP
 199 関数
 200 .BR localtime ()
 201 は、カレンダー時刻 \fItimep\fP を
 202 ユーザが指定したタイムゾーンでの時刻要素別の表現へ変換する。
 203 この関数は
 204 .BR tzset (3)
 205 を呼び出したかのように振舞い、
 206 大域変数 \fItzname\fP に現在のタイムゾーンの情報を設定する。
 207 また、\fItimezone\fP に協定世界時 (UTC) とローカル標準時との
 208 時差の秒数を設定し、
 209 一年の一部で夏時間が適用される場合は \fIdaylight\fP に 0 が設定される。
 210 返り値は静的に確保された構造体を指しており、この後で
 211 日付や時刻に関する関数のいずれかが呼び出されると
 212 上書きされる可能性がある。
 213 .BR localtime_r ()
 214 も同様だが、
 215 データはユーザーが用意した構造体に格納される。
 216 この関数は \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP
 217 を設定する必要はない。
 218 .PP
 219 関数
 220 .BR asctime ()
 221 は、要素別の時刻 \fItm\fP を
 222 .BR ctime ()
 223 と同じ形式の NULL 終端された文字列へ変換する。
 224 返り値は静的に割り当てられた文字列へのポインタである。この文字列は、
 225 日付・時刻関数のいずれかが呼び出されると上書きされることがある。
 226 リエントラント版である
 227 .BR asctime_r ()
 228 も同様だが、
 229 文字列はユーザーが用意したバッファに格納される。バッファのサイズは
 230 少なくとも 26 バイト以上でなければならない。
 231 .PP
 232 関数
 233 .BR mktime ()
 234 は、(ローカルタイムで記述されている) 要素別の時刻を
 235 カレンダー時刻へ変換する。この際、呼び出し元がフィールド
 236 .I tm_wday
 237 と
 238 .I tm_yday
 239 で指定した値は無視される。
 240 .BR mktime ()
 241 は、フィールド
 242 .I tm_isdst
 243 で指定された値により、
 244 .I tm
 245 構造体で渡された時刻で夏時間 (daylight saving time; DST) が有効になって
 246 いるかを知る。
 247 正の値は夏時間が有効であることを意味する。
 248 負の値であれば、
 249 .BR mktime ()
 250 は (タイムゾーン情報とシステムのデータベースを使って)
 251 指定された時刻で夏時間が有効かどうかを判断する必要があることを意味する。
 252
 253 .BR mktime ()
 254 は
 255 .I tm
 256 構造体の各フィールドを以下のように修正する。
 257 .I tm_wday
 258 と
 259 .I tm_yday
 260 には他のフィールドの内容から求めた値を設定する。
 261 構造体の要素が有効な範囲にない場合、正規化される
 262 (例えば、10 月 40 日は 11 月 9 日に変更される)。
 263 .I tm_isdst
 264 には (最初の値にかかわらず) 正の値か 0 が設定される。
 265 正の値は指定された時間で夏時間が有効であることを示し、
 266 0 は無効であることを示す。
 267 関数
 268 .BR mktime ()
 269 を呼び出すと、
 270 大域変数 \fItzname\fP が現在のタイムゾーンに設定される。
 271
 272 要素別の時刻をカレンダー時刻 (紀元 (Epoch) からの秒数) で表現できない場合、
 273 .BR mktime ()
 274 は
 275 .I (time_t)\ (-1)
 276 を返し、要素別の時刻の構造体メンバーを変更しない。
 277 .SH 返り値
 278 各関数はそれぞれ前述した値を返す。エラーの場合は NULL
 279 .RB ( mktime ()
 280 では \-1) を返す。
 281 .SH 準拠
 282 POSIX.1-2001.
 283 C89 と C99 では
 284 .BR asctime (),
 285 .BR ctime (),
 286 .BR gmtime (),
 287 .BR localtime (),
 288 .BR mktime ()
 289 が規定されている。
 290 POSIX.1-2008 は、
 291 .BR asctime (),
 292 .BR asctime_r (),
 293 .BR ctime (),
 294 .BR ctime_r ()
 295 を廃止予定としている。
 296 代わりに、
 297 .BR strftime (3)
 298 の使用が推奨されている。
 299 .SH 注意
 300 .BR asctime (),
 301 .BR ctime (),
 302 .BR gmtime (),
 303 .BR localtime ()
 304 の 4 つの関数は静的データへのポインタを返すので、スレッドセーフではない。
 305 これらの関数のスレッドセーフ版である
 306 .BR asctime_r (),
 307 .BR ctime_r (),
 308 .BR gmtime_r (),
 309 .BR localtime_r ()
 310 は SUSv2 で規定されており、
 311 libc 5.2.5 以降で利用できる。
 312
 313 POSIX.1-2001 では、「関数
 314 .BR asctime (),
 315 .BR ctime (),
 316 .BR gmtime (),
 317 .BR localtime ()
 318 は、要素別の時刻の構造体か
 319 .I char
 320 型の配列かのどちらかの静的オブジェクトを返すものとする。
 321 これらの関数のいずれかを実行すると、他の関数のどれかがこれらの
 322 静的オブジェクトのどちらかに格納して返した情報が上書きされるかも
 323 しれない。」となっている。
 324 このことは glibc の実装で起こりうる。
 325 .LP
 326 glibc を含む多くの実装では、
 327 .I tm_mday
 328 に 0 を指定すると前月の最終日を意味していると解釈される。
 329 .LP
 330 glibc では、
 331 .I <time.h>
 332 がインクルードされる前に
 333 .B _BSD_SOURCE
 334 が定義されると、
 335 \fIstruct tm\fP に以下のフィールドが追加される。
 336 .sp
 337 .RS
 338 .nf
 339 long tm_gmtoff;           /* Seconds east of UTC */
 340 const char *tm_zone;      /* Timezone abbreviation */
 341 .fi
 342 .RE
 343 .sp
 344 これは BSD 拡張であり、4.3BSD-Reno から現れた。
 345
 346 POSIX.1-2004 によると、
 347 .BR localtime ()
 348 はあたかも
 349 .BR tzset (3)
 350 が呼ばれたかのように振舞うことが要求されているが、
 351 .BR localtime_r ()
 352 にはこの要件はない。
 353 .\" http://thread.gmane.org/gmane.comp.time.tz/2034/ を参照。
 354 移植性が必要なコードでは、
 355 .BR localtime_r ()
 356 の前に
 357 .BR tzset (3)
 358 を呼び出しておくべきである。
 359 .SH 関連項目
 360 .BR date (1),
 361 .BR gettimeofday (2),
 362 .BR time (2),
 363 .BR utime (2),
 364 .BR clock (3),
 365 .BR difftime (3),
 366 .BR strftime (3),
 367 .BR strptime (3),
 368 .BR timegm (3),
 369 .BR tzset (3),
 370 .BR time (7)