draft/man3/getdate.3

   1 .\" Copyright 2001 walter harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\"
  25 .\" Modified, 2001-12-26, aeb
  26 .\" 2008-09-07, mtk, Various rewrites; added an example program.
  27 .\"
  28 .\" Japanese Version Copyright (c) 2002 NAKANO Takeo
  29 .\" and Copyright (c) 2008, Akihiro MOTOKI all rights reserved.
  30 .\"
  31 .\" Translated 2002-01-12, NAKANO Takeo <nakano@apm.seikei.ac.jp>
  32 .\" Updated 2008-09-20, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.09
  33 .\"
  34 .\"WORD:        broken-down time        要素別の時刻
  35 .\"
  36 .TH GETDATE 3 2010-09-20 "" "Linux Programmer's Manual"
  37 .\"O .SH NAME
  38 .SH 名前
  39 .\"O getdate, getdate_r \- convert a date-plus-time string to broken-down time
  40 getdate, getdate_r \- 日付と時刻の文字列を要素別の時刻に変換する
  41 .\"O .SH SYNOPSIS
  42 .SH 書式
  43 .B "#include <time.h>"
  44 .sp
  45 .BI "struct tm *getdate(const char *" string );
  46 .sp
  47 .B "extern int getdate_err;"
  48 .sp
  49 .B "#include <time.h>"
  50 .sp
  51 .BI "int getdate_r(const char *" string ", struct tm *" res );
  52 .sp
  53 .in -4n
  54 .\"O Feature Test Macro Requirements for glibc (see
  55 .\"O .BR feature_test_macros (7)):
  56 glibc 向けの機能検査マクロの要件
  57 .RB ( feature_test_macros (7)
  58 参照):
  59 .in
  60 .sp
  61 .BR getdate ():
  62 .ad l
  63 .RS 4
  64 _XOPEN_SOURCE\ >=\ 500 ||
  65 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  66 .RE
  67 .br
  68 .BR getdate_r ():
  69 .ad l
  70 .RS 4
  71 _GNU_SOURCE
  72 .RE
  73 .ad
  74 .\"O .SH DESCRIPTION
  75 .SH 説明
  76 .\"O The function
  77 .\"O .BR getdate ()
  78 .\"O converts a string representation of a date and time,
  79 .\"O contained in the buffer pointed to by
  80 .\"O .IR string ,
  81 .\"O into a broken-down time.
  82 .BR getdate ()
  83 関数は、
  84 .I string
  85 が指すバッファに格納された文字列表現の日付と時刻を、
  86 要素別の時刻 (broken-down time) に変換する。
  87 .\"O The broken-down time is stored in a
  88 .\"O .I tm
  89 .\"O structure, and a pointer to this
  90 .\"O structure is returned as the function result.
  91 .\"O This
  92 .\"O .I tm
  93 .\"O structure is allocated in static storage,
  94 .\"O and consequently it will be overwritten by further calls to
  95 .\"O .BR getdate ().
  96 要素別の時刻は
  97 .I tm
  98 構造体に格納され、この構造体へのポインタが関数の結果として返される。
  99 この
 100 .I tm
 101 構造体は静的なメモリ領域にあり、
 102 .BR getdate ()
 103 のそれ以降の呼び出しで上書きされるかもされない。
 104 .\"O
 105 .PP
 106 .\"O In contrast to
 107 .\"O .BR strptime (3),
 108 .\"O (which has a
 109 .\"O .I format
 110 .\"O argument),
 111 .\"O .BR getdate ()
 112 .\"O uses the formats found in the file
 113 .\"O whose full pathname is given in the environment variable
 114 .\"O .BR DATEMSK .
 115 .\"O The first line in the file that matches the given input string
 116 .\"O is used for the conversion.
 117 .RI ( format
 118 引き数でフォーマットを指定する)
 119 .BR strptime (3)
 120 とは違い、
 121 .BR getdate ()
 122 は環境変数
 123 .B DATEMSK
 124 で指定されたフルパス名のファイルに書いてあるフォーマットを用いる。
 125 .\"O
 126 .PP
 127 .\"O The matching is done case insensitively.
 128 .\"O Superfluous whitespace, either in the pattern or in the string to
 129 .\"O be converted, is ignored.
 130 マッチの際には大文字小文字を区別しない。
 131 パターン中でも変換される文字列中でも、余分な空白文字は無視される。
 132 .\"O
 133 .PP
 134 .\"O The conversion specifications that a pattern can contain are those given for
 135 .\"O .BR strptime (3).
 136 .\"O One more conversion specification is specified in POSIX.1-2001:
 137 パターンに指定できる変換指定は、
 138 .BR strptime (3)
 139 のものと同じである。
 140 POSIX.1-2001 では一つの変換指定が追加で規定されている。
 141 .TP
 142 .B %Z
 143 .\"O Timezone name.
 144 .\"O This is not implemented in glibc.
 145 タイムゾーンの名前。
 146 glibc では実装されていない。
 147 .LP
 148 .\"O When
 149 .\"O .B %Z
 150 .\"O is given, the structure containing the broken-down time
 151 .\"O is initialized with values corresponding to the current
 152 .\"O time in the given timezone.
 153 .\"O Otherwise, the structure is initialized to the broken-down time
 154 .\"O corresponding to the current local time (as by a call to
 155 .\"O .BR localtime (3)).
 156 .B %Z
 157 が指定された場合、要素別の時刻を格納する構造体は、
 158 指定されたタイムゾーンにおける現在時刻に対応する値で初期化される。
 159 指定されていない場合、この構造体は現在のローカルタイムに対応する
 160 要素別の時刻で初期化される
 161 .RB ( localtime (3)
 162 を呼び出した場合と同じ)。
 163 .LP
 164 .\"O When only the weekday is given, the day is taken to be the first such day
 165 .\"O on or after today.
 166 曜日だけが指定された場合、
 167 今日または今日以降で、
 168 その曜日に合致する最初の日が採用される。
 169 .LP
 170 .\"O When only the month is given (and no year), the month is taken to
 171 .\"O be the first such month equal to or after the current month.
 172 .\"O If no day is given, it is the first day of the month.
 173 (年なしで) 月だけが指定された場合、
 174 今月または今月以降で、
 175 その月に合致する最初の月が採用される。
 176 .LP
 177 .\"O When no hour, minute and second are given, the current
 178 .\"O hour, minute and second are taken.
 179 時・分・秒がいずれも指定されなかった場合、
 180 現在の時・分・秒が採用される。
 181 .LP
 182 .\"O If no date is given, but we know the hour, then that hour is taken
 183 .\"O to be the first such hour equal to or after the current hour.
 184 日付の指定がなかったが、時間 (hour) だけ指定された場合は、
 185 現在の時間またはそれ以降で、その指定に合致する最初の時間が採用される。
 186
 187 .\"O .BR getdate_r ()
 188 .\"O is a GNU extension that provides a reentrant version of
 189 .\"O .BR getdate ().
 190 .\"O Rather than using a global variable to report errors and a static buffer
 191 .\"O to return the broken down time,
 192 .\"O it returns errors via the function result value,
 193 .\"O and returns the resulting broken-down time in the
 194 .\"O caller-allocated buffer pointed to by the argument
 195 .\"O .IR res .
 196 .BR getdate_r ()
 197 は GNU 拡張で
 198 .BR getdate ()
 199 のリエントラント版を提供している。
 200 .BR getdate_r ()
 201 では、エラーを報告するのにグローバル変数を使用したり、
 202 要素別の時刻を返すのに静的なバッファを使用したりせず、
 203 エラーを関数の返り値経由で報告し、要素別の時刻を
 204 引き数
 205 .I res
 206 が指し示す呼び出し側で割り当てたバッファに格納して返す。
 207 .\"O .SH "RETURN VALUE"
 208 .SH 返り値
 209 .\"O When successful,
 210 .\"O .BR getdate ()
 211 .\"O returns a pointer to a
 212 .\"O .IR "struct tm" .
 213 .\"O Otherwise, it returns NULL and sets the global variable
 214 .\"O .IR getdate_err
 215 .\"O to one of the error numbers shown below.
 216 .\"O Changes to
 217 .\"O .I errno
 218 .\"O are unspecified.
 219 成功すると、
 220 .BR getdate ()
 221 は
 222 .I struct tm
 223 へのポインタを返す。
 224 失敗すると NULL を返し、グローバル変数
 225 .I getdate_err
 226 に以下に示すエラー番号のいずれか一つを設定する。
 227 .I errno
 228 の変更については規定されていない。
 229
 230 .\"O On success
 231 .\"O .BR getdate_r ()
 232 .\"O returns 0;
 233 .\"O on error it returns one of the error numbers shown below.
 234 成功すると、
 235 .BR getdate_r ()
 236 は 0 を返す。
 237 失敗すると、以下に示すエラー番号のいずれか一つを返す。
 238 .\"O .SH ERRORS
 239 .SH エラー
 240 .\"O The following errors are returned via
 241 .\"O .IR getdate_err
 242 .\"O (for
 243 .\"O .BR getdate ())
 244 .\"O or as the function result (for
 245 .\"O .BR getdate_r ()):
 246 以下のエラーが、
 247 .RB ( getdate ()
 248 では)
 249 .I getdate_err
 250 経由で返され、
 251 .RB ( getdate_r ()
 252 では) 関数の返り値として返される。
 253 .TP 4n
 254 .B 1
 255 .\"O The
 256 .\"O .B DATEMSK
 257 .\"O environment variable is not defined, or its value is an empty string.
 258 環境変数
 259 .B DATEMASK
 260 が未定義、またはその値が空文字列である。
 261 .TP
 262 .B 2
 263 .\"O The template file specified by
 264 .\"O .B DATEMSK
 265 .\"O cannot be opened for reading.
 266 .B DATEMSK
 267 で指定されたテンプレートファイルを読み込み用にオープンできない。
 268 .TP
 269 .B 3
 270 .\"O Failed to get file status information.
 271 ファイルのステータス情報が取得できない。
 272 .\" stat()
 273 .TP
 274 .B 4
 275 .\"O The template file is not a regular file.
 276 テンプレートファイルが通常のファイルでない。
 277 .TP
 278 .B 5
 279 .\"O An error was encountered while reading the template file.
 280 テンプレートファイルの読み込み中にエラーが起こった。
 281 .TP
 282 .B 6
 283 .\"O Memory allocation failed (not enough memory available).
 284 .\"O .\" Error 6 doesn't seem to occur in glibc
 285 メモリの割り当てに失敗した (メモリが足りない)。
 286 .\" エラー 6 は glibc では発生しないように見える。
 287 .TP
 288 .B 7
 289 .\"O There is no line in the file that matches the input.
 290 入力にマッチしたファイルに、行が含まれていない。
 291 .TP
 292 .B 8
 293 .\"O Invalid input specification.
 294 入力指定が正しくない。
 295 .\"O .SH ENVIRONMENT
 296 .SH 環境変数
 297 .TP
 298 .B DATEMSK
 299 .\"O File containing format patterns.
 300 書式パターンを含むファイル。
 301 .TP
 302 .BR TZ ", " LC_TIME
 303 .\"O Variables used by
 304 .\"O .BR strptime (3).
 305 .BR strptime (3)
 306 が用いる変数。
 307 .\"O .SH "CONFORMING TO"
 308 .SH 準拠
 309 POSIX.1-2001.
 310 .\"O .SH NOTES
 311 .SH 注意
 312 .\"O The POSIX.1-2001 specification for
 313 .\"O .BR strptime (3)
 314 .\"O contains conversion specifications using the
 315 .\"O .B %E
 316 .\"O or
 317 .\"O .B %O
 318 .\"O modifier, while such specifications are not given for
 319 .\"O .BR getdate ().
 320 .\"O In glibc,
 321 .\"O .BR getdate ()
 322 .\"O is implemented using
 323 .\"O .BR strptime (3),
 324 .\"O so that precisely the same conversions are supported by both.
 325 POSIX.1-2001 仕様では、
 326 .BR strptime (3)
 327 については
 328 .B %E
 329 や
 330 .B %O
 331 といった修正子を用いた変換指定を規定しているが、
 332 .BR getdate ()
 333 についてはこのような修飾子の規定はない。
 334 glibc では、
 335 .BR getdate ()
 336 は
 337 .BR strptime (3)
 338 を用いて実装されており、
 339 両者では全く同じ変換が両者でサポートされている。
 340 .\"O .SH EXAMPLE
 341 .SH 例
 342 .\"O The program below calls
 343 .\"O .BR getdate ()
 344 .\"O for each of its command-line arguments,
 345 .\"O and for each call displays the values in the fields of the returned
 346 .\"O .I tm
 347 .\"O structure.
 348 .\"O The following shell session demonstrates the operation of the program:
 349 以下のプログラムは、コマンドライン引き数のそれぞれについて
 350 .BR getdate ()
 351 を呼び出し、それぞれについて返された
 352 .I tm
 353 構造体のフィールド値を表示する。
 354 次のシェル・セッションは、プログラムの動作例である。
 355
 356 .in +4n
 357 .nf
 358 .RB "$" " TFILE=$PWD/tfile"
 359 .RB "$" " echo \(aq%A\(aq > $TFILE " "      # Full weekday name"
 360 .RB "$" " echo \(aq%T\(aq >> $TFILE" "      # ISO date (YYYY-MM-DD)"
 361 .RB "$" " echo \(aq%F\(aq >> $TFILE" "      # Time (HH:MM:SS)"
 362 .RB "$" " date"
 363 .RB "$" " export DATEMSK=$TFILE"
 364 .RB "$" " ./a.out Tuesday \(aq2009-12-28\(aq \(aq12:22:33\(aq"
 365 Sun Sep  7 06:03:36 CEST 2008
 366 Call 1 ("Tuesday") succeeded:
 367     tm_sec   = 36
 368     tm_min   = 3
 369     tm_hour  = 6
 370     tm_mday  = 9
 371     tm_mon   = 8
 372     tm_year  = 108
 373     tm_wday  = 2
 374     tm_yday  = 252
 375     tm_isdst = 1
 376 Call 2 ("2009-12-28") succeeded:
 377     tm_sec   = 36
 378     tm_min   = 3
 379     tm_hour  = 6
 380     tm_mday  = 28
 381     tm_mon   = 11
 382     tm_year  = 109
 383     tm_wday  = 1
 384     tm_yday  = 361
 385     tm_isdst = 0
 386 Call 3 ("12:22:33") succeeded:
 387     tm_sec   = 33
 388     tm_min   = 22
 389     tm_hour  = 12
 390     tm_mday  = 7
 391     tm_mon   = 8
 392     tm_year  = 108
 393     tm_wday  = 0
 394     tm_yday  = 250
 395     tm_isdst = 1
 396 .fi
 397 .in
 398 .\"O .SS Program source
 399 .SS プログラムのソース
 400 \&
 401 .nf
 402 #define _GNU_SOURCE 500
 403 #include <time.h>
 404 #include <stdio.h>
 405 #include <stdlib.h>
 406
 407 int
 408 main(int argc, char *argv[])
 409 {
 410     struct tm *tmp;
 411     int j;
 412
 413     for (j = 1; j < argc; j++) {
 414         tmp = getdate(argv[j]);
 415
 416         if (tmp == NULL) {
 417             printf("Call %d failed; getdate_err = %d\\n",
 418                    j, getdate_err);
 419             continue;
 420         }
 421
 422         printf("Call %d (\\"%s\\") succeeded:\\n", j, argv[j]);
 423         printf("    tm_sec   = %d\\n", tmp\->tm_sec);
 424         printf("    tm_min   = %d\\n", tmp\->tm_min);
 425         printf("    tm_hour  = %d\\n", tmp\->tm_hour);
 426         printf("    tm_mday  = %d\\n", tmp\->tm_mday);
 427         printf("    tm_mon   = %d\\n", tmp\->tm_mon);
 428         printf("    tm_year  = %d\\n", tmp\->tm_year);
 429         printf("    tm_wday  = %d\\n", tmp\->tm_wday);
 430         printf("    tm_yday  = %d\\n", tmp\->tm_yday);
 431         printf("    tm_isdst = %d\\n", tmp\->tm_isdst);
 432     }
 433
 434     exit(EXIT_SUCCESS);
 435 }
 436 .fi
 437 .\"O .SH "SEE ALSO"
 438 .SH 関連項目
 439 .BR time (2),
 440 .BR localtime (3),
 441 .BR setlocale (3),
 442 .BR strftime (3),
 443 .BR strptime (3)