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 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" Modified, 2001-12-26, aeb
  28 .\" 2008-09-07, mtk, Various rewrites; added an example program.
  29 .\"
  30 .\"*******************************************************************
  31 .\"
  32 .\" This file was generated with po4a. Translate the source file.
  33 .\"
  34 .\"*******************************************************************
  35 .\"
  36 .\" Japanese Version Copyright (c) 2002 NAKANO Takeo
  37 .\" and Copyright (c) 2008, Akihiro MOTOKI all rights reserved.
  38 .\"
  39 .TH GETDATE 3 2014\-06\-13 "" "Linux Programmer's Manual"
  40 .SH 名前
  41 getdate, getdate_r \- 日付と時刻の文字列を要素別の時刻に変換する
  42 .SH 書式
  43 \fB#include <time.h>\fP
  44 .sp
  45 \fBstruct tm *getdate(const char *\fP\fIstring\fP\fB);\fP
  46 .sp
  47 \fBextern int getdate_err;\fP
  48 .sp
  49 \fB#include <time.h>\fP
  50 .sp
  51 \fBint getdate_r(const char *\fP\fIstring\fP\fB, struct tm *\fP\fIres\fP\fB);\fP
  52 .sp
  53 .in -4n
  54 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  55 .in
  56 .sp
  57 \fBgetdate\fP():
  58 .ad l
  59 .RS 4
  60 _XOPEN_SOURCE\ >=\ 500 || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  61 .RE
  62 .br
  63 \fBgetdate_r\fP():
  64 .ad l
  65 .RS 4
  66 _GNU_SOURCE
  67 .RE
  68 .ad
  69 .SH 説明
  70 \fBgetdate\fP()  関数は、 \fIstring\fP が指すバッファーに格納された文字列表現の日付と時刻を、 要素別の時刻 (broken\-down
  71 time) に変換する。 要素別の時刻は \fItm\fP 構造体に格納され、この構造体へのポインターが関数の結果として返される。 この \fItm\fP
  72 構造体は静的なメモリー領域にあり、 \fBgetdate\fP()  のそれ以降の呼び出しで上書きされるかもされない。
  73
  74 (\fIformat\fP 引き数でフォーマットを指定する)  \fBstrptime\fP(3)  とは違い、 \fBgetdate\fP()  は環境変数
  75 \fBDATEMSK\fP で指定されたフルパス名のファイルに書いてあるフォーマットを用いる。
  76
  77 マッチの際には大文字小文字を区別しない。 パターン中でも変換される文字列中でも、余分な空白文字は無視される。
  78
  79 パターンに指定できる変換指定は、 \fBstrptime\fP(3)  のものと同じである。 POSIX.1\-2001
  80 では一つの変換指定が追加で規定されている。
  81 .TP
  82 \fB%Z\fP
  83 タイムゾーンの名前。 glibc では実装されていない。
  84 .LP
  85 \fB%Z\fP が指定された場合、要素別の時刻を格納する構造体は、 指定されたタイムゾーンにおける現在時刻に対応する値で初期化される。
  86 指定されていない場合、この構造体は現在のローカルタイムに対応する 要素別の時刻で初期化される (\fBlocaltime\fP(3)
  87 を呼び出した場合と同じ)。
  88 .LP
  89 曜日だけが指定された場合、 今日または今日以降で、 その曜日に合致する最初の日が採用される。
  90 .LP
  91 (年なしで) 月だけが指定された場合、 今月または今月以降で、 その月に合致する最初の月が採用される。
  92 .LP
  93 時・分・秒がいずれも指定されなかった場合、 現在の時・分・秒が採用される。
  94 .LP
  95 日付の指定がなかったが、時間 (hour) だけ指定された場合は、 現在の時間またはそれ以降で、その指定に合致する最初の時間が採用される。
  96
  97 \fBgetdate_r\fP()  は GNU 拡張で \fBgetdate\fP()  のリエントラント版を提供している。 \fBgetdate_r\fP()
  98 では、エラーを報告するのにグローバル変数を使用したり、 要素別の時刻を返すのに静的なバッファーを使用したりせず、
  99 エラーを関数の返り値経由で報告し、要素別の時刻を 引き数 \fIres\fP が指し示す呼び出し側で割り当てたバッファーに格納して返す。
 100 .SH 返り値
 101 成功すると、 \fBgetdate\fP()  は \fIstruct tm\fP へのポインターを返す。 失敗すると NULL を返し、グローバル変数
 102 \fIgetdate_err\fP に以下に示すエラー番号のいずれか一つを設定する。 \fIerrno\fP の変更については規定されていない。
 103
 104 成功すると、 \fBgetdate_r\fP()  は 0 を返す。 失敗すると、以下に示すエラー番号のいずれか一つを返す。
 105 .SH エラー
 106 以下のエラーが、 (\fBgetdate\fP()  では)  \fIgetdate_err\fP 経由で返され、 (\fBgetdate_r\fP()  では)
 107 関数の返り値として返される。
 108 .TP  4n
 109 \fB1\fP
 110 環境変数 \fBDATEMASK\fP が未定義、またはその値が空文字列である。
 111 .TP
 112 \fB2\fP
 113 \fBDATEMSK\fP で指定されたテンプレートファイルを読み込み用にオープンできない。
 114 .TP
 115 \fB3\fP
 116 .\" stat()
 117 ファイルのステータス情報が取得できない。
 118 .TP
 119 \fB4\fP
 120 テンプレートファイルが通常のファイルでない。
 121 .TP
 122 \fB5\fP
 123 テンプレートファイルの読み込み中にエラーが起こった。
 124 .TP
 125 \fB6\fP
 126 .\" Error 6 doesn't seem to occur in glibc
 127 メモリーの割り当てに失敗した (メモリーが足りない)。
 128 .TP
 129 \fB7\fP
 130 入力にマッチしたファイルに、行が含まれていない。
 131 .TP
 132 \fB8\fP
 133 入力指定が正しくない。
 134 .SH 環境変数
 135 .TP
 136 \fBDATEMSK\fP
 137 書式パターンを含むファイル。
 138 .TP
 139 \fBTZ\fP, \fBLC_TIME\fP
 140 \fBstrptime\fP(3)  が用いる変数。
 141 .SH 属性
 142 .SS "マルチスレッディング (pthreads(7) 参照)"
 143 \fBgetdate\fP() 関数はスレッドセーフではない。
 144 .LP
 145 \fBgetdate_r\fP() 関数はスレッドセーフである。
 146 .SH 準拠
 147 POSIX.1\-2001.
 148 .SH 注意
 149 POSIX.1\-2001 仕様では、 \fBstrptime\fP(3)  については \fB%E\fP や \fB%O\fP
 150 といった修正子を用いた変換指定を規定しているが、 \fBgetdate\fP()  についてはこのような修飾子の規定はない。 glibc では、
 151 \fBgetdate\fP()  は \fBstrptime\fP(3)  を用いて実装されており、 両者では全く同じ変換が両者でサポートされている。
 152 .SH 例
 153 以下のプログラムは、コマンドライン引き数のそれぞれについて \fBgetdate\fP()  を呼び出し、それぞれについて返された \fItm\fP
 154 構造体のフィールド値を表示する。 次のシェルセッションは、プログラムの動作例である。
 155
 156 .in +4n
 157 .nf
 158 $\fB TFILE=$PWD/tfile\fP
 159 $\fB echo \(aq%A\(aq > $TFILE \fP      # Full name of the day of the week
 160 $\fB echo \(aq%T\(aq >> $TFILE\fP      # ISO date (YYYY\-MM\-DD)
 161 $\fB echo \(aq%F\(aq >> $TFILE\fP      # Time (HH:MM:SS)
 162 $\fB date\fP
 163 $\fB export DATEMSK=$TFILE\fP
 164 $\fB ./a.out Tuesday \(aq2009\-12\-28\(aq \(aq12:22:33\(aq\fP
 165 Sun Sep  7 06:03:36 CEST 2008
 166 Call 1 ("Tuesday") succeeded:
 167     tm_sec   = 36
 168     tm_min   = 3
 169     tm_hour  = 6
 170     tm_mday  = 9
 171     tm_mon   = 8
 172     tm_year  = 108
 173     tm_wday  = 2
 174     tm_yday  = 252
 175     tm_isdst = 1
 176 Call 2 ("2009\-12\-28") succeeded:
 177     tm_sec   = 36
 178     tm_min   = 3
 179     tm_hour  = 6
 180     tm_mday  = 28
 181     tm_mon   = 11
 182     tm_year  = 109
 183     tm_wday  = 1
 184     tm_yday  = 361
 185     tm_isdst = 0
 186 Call 3 ("12:22:33") succeeded:
 187     tm_sec   = 33
 188     tm_min   = 22
 189     tm_hour  = 12
 190     tm_mday  = 7
 191     tm_mon   = 8
 192     tm_year  = 108
 193     tm_wday  = 0
 194     tm_yday  = 250
 195     tm_isdst = 1
 196 .fi
 197 .in
 198 .SS プログラムのソース
 199 \&
 200 .nf
 201 #define _GNU_SOURCE
 202 #include <time.h>
 203 #include <stdio.h>
 204 #include <stdlib.h>
 205
 206 int
 207 main(int argc, char *argv[])
 208 {
 209     struct tm *tmp;
 210     int j;
 211
 212     for (j = 1; j < argc; j++) {
 213         tmp = getdate(argv[j]);
 214
 215         if (tmp == NULL) {
 216             printf("Call %d failed; getdate_err = %d\en",
 217                    j, getdate_err);
 218             continue;
 219         }
 220
 221         printf("Call %d (\e"%s\e") succeeded:\en", j, argv[j]);
 222         printf("    tm_sec   = %d\en", tmp\->tm_sec);
 223         printf("    tm_min   = %d\en", tmp\->tm_min);
 224         printf("    tm_hour  = %d\en", tmp\->tm_hour);
 225         printf("    tm_mday  = %d\en", tmp\->tm_mday);
 226         printf("    tm_mon   = %d\en", tmp\->tm_mon);
 227         printf("    tm_year  = %d\en", tmp\->tm_year);
 228         printf("    tm_wday  = %d\en", tmp\->tm_wday);
 229         printf("    tm_yday  = %d\en", tmp\->tm_yday);
 230         printf("    tm_isdst = %d\en", tmp\->tm_isdst);
 231     }
 232
 233     exit(EXIT_SUCCESS);
 234 }
 235 .fi
 236 .SH 関連項目
 237 \fBtime\fP(2), \fBlocaltime\fP(3), \fBsetlocale\fP(3), \fBstrftime\fP(3), \fBstrptime\fP(3)
 238 .SH この文書について
 239 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 240 である。プロジェクトの説明とバグ報告に関する情報は
 241 http://www.kernel.org/doc/man\-pages/ に書かれている。