GETDATE(3)

名前
getdate, getdate_r - 日付と時刻の文字列を要素別の時刻に変換する

書式
#include <time.h>

struct tm *getdate(const char *string);

extern int getdate_err;

#include <time.h>

int getdate_r(const char *string, struct tm *res);

    glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):

getdate():
     _XOPEN_SOURCE >= 500
getdate_r():
    _GNU_SOURCE

説明
getdate() 関数は、 string が指すバッファーに格納された文字列表現の日付と時刻を、 要素別の時刻 (broken-down time) に変換する。 要素別の時刻は tm 構造体に格納され、この構造体へのポインターが関数の結果として返される。 この tm 構造体は静的なメモリー領域にあり、 getdate() のそれ以降の呼び出しで上書きされるかもされない。

(format 引数でフォーマットを指定する) strptime(3) とは違い、 getdate() は環境変数 DATEMSK で指定されたフルパス名のファイルに書いてあるフォーマットを用いる。

マッチの際には大文字小文字を区別しない。 パターン中でも変換される文字列中でも、余分な空白文字は無視される。

パターンに指定できる変換指定は、 strptime(3) のものと同じである。 POSIX.1-2001 では一つの変換指定が追加で規定されている。

%Z  タイムゾーンの名前。 glibc では実装されていない。

%Z が指定された場合、要素別の時刻を格納する構造体は、 指定されたタイムゾーンにおける現在時刻に対応する値で初期化される。 指定されていない場合、この構造体は現在のローカルタイムに対応する 要素別の時刻で初期化される (localtime(3) を呼び出した場合と同じ)。

曜日だけが指定された場合、 今日または今日以降で、 その曜日に合致する最初の日が採用される。

(年なしで) 月だけが指定された場合、 今月または今月以降で、 その月に合致する最初の月が採用される。

時・分・秒がいずれも指定されなかった場合、 現在の時・分・秒が採用される。

日付の指定がなかったが、時間 (hour) だけ指定された場合は、 現在の時間またはそれ以降で、その指定に合致する最初の時間が採用される。

getdate_r() は GNU 拡張で getdate() のリエントラント版を提供している。 getdate_r() では、エラーを報告するのにグローバル変数を使用したり、 要素別の時刻を返すのに静的なバッファーを使用したりせず、 エラーを関数の返り値経由で報告し、要素別の時刻を 引数 res が指し示す呼び出し側で割り当てたバッファーに格納して返す。

返り値
成功すると、 getdate() は struct tm へのポインターを返す。 失敗すると NULL を返し、グローバル変数 getdate_err に以下に示すエラー番号のいずれか一つを設定する。 errno の変更については規定されていない。

成功すると、 getdate_r() は 0 を返す。 失敗すると、以下に示すエラー番号のいずれか一つを返す。

エラー
以下のエラーが、 (getdate() では) getdate_err 経由で返され、 (getdate_r() では) 関数の返り値として返される。

1   環境変数 DATEMASK が未定義、またはその値が空文字列である。

2   DATEMSK で指定されたテンプレートファイルを読み込み用にオープンできない。

3   ファイルのステータス情報が取得できない。

4   テンプレートファイルが通常のファイルでない。

5   テンプレートファイルの読み込み中にエラーが起こった。

6   メモリーの割り当てに失敗した (メモリーが足りない)。

7   入力にマッチしたファイルに、行が含まれていない。

8   入力指定が正しくない。

環境変数

DATEMSK
    書式パターンを含むファイル。

TZ, LC_TIME
    strptime(3) が用いる変数。

属性
この節で使用されている用語の説明については、 attributes(7) を参照。
インターフェース | 属性 | 値
getdate() | Thread safety | MT-Unsafe race:getdate env locale
getdate_r() | Thread safety | MT-Safe env locale

準拠
 POSIX.1-2001, POSIX.1-2008.

注意
POSIX.1 仕様では、 strptime(3) については %E や %O といった修正子を用いた変換指定を規定しているが、 getdate() についてはこのような修飾子の規定はない。 glibc では、 getdate() は strptime(3) を用いて実装されており、 両者では全く同じ変換が両者でサポートされている。

例
以下のプログラムは、コマンドライン引数のそれぞれについて getdate() を呼び出し、それぞれについて返された tm 構造体のフィールド値を表示する。 次のシェルセッションは、プログラムの動作例である。

    $ TFILE=$PWD/tfile
    $ echo '%A' > $TFILE       # Full name of the day of the week
    $ echo '%T' >> $TFILE      # ISO date (YYYY-MM-DD)
    $ echo '%F' >> $TFILE      # Time (HH:MM:SS)
    $ date
    $ export DATEMSK=$TFILE
    $ ./a.out Tuesday '2009-12-28' '12:22:33'
    Sun Sep  7 06:03:36 CEST 2008
    Call 1 ("Tuesday") succeeded:
        tm_sec   = 36
        tm_min   = 3
        tm_hour  = 6
        tm_mday  = 9
        tm_mon   = 8
        tm_year  = 108
        tm_wday  = 2
        tm_yday  = 252
        tm_isdst = 1
    Call 2 ("2009-12-28") succeeded:
        tm_sec   = 36
        tm_min   = 3
        tm_hour  = 6
        tm_mday  = 28
        tm_mon   = 11
        tm_year  = 109
        tm_wday  = 1
        tm_yday  = 361
        tm_isdst = 0
    Call 3 ("12:22:33") succeeded:
        tm_sec   = 33
        tm_min   = 22
        tm_hour  = 12
        tm_mday  = 7
        tm_mon   = 8
        tm_year  = 108
        tm_wday  = 0
        tm_yday  = 250
        tm_isdst = 1

  プログラムのソース
    #define _GNU_SOURCE
    #include <time.h>
    #include <stdio.h>
    #include <stdlib.h>

     int
    main(int argc, char *argv[])
    {
        struct tm *tmp;

         for (int j = 1; j < argc; j++) {
            tmp = getdate(argv[j]);

            if (tmp == NULL) {
                printf("Call %d failed; getdate_err = %d\n",
                       j, getdate_err);
                continue;
            }

            printf("Call %d (\"%s\") succeeded:\n", j, argv[j]);
            printf("    tm_sec   = %d\n", tmp->tm_sec);
            printf("    tm_min   = %d\n", tmp->tm_min);
            printf("    tm_hour  = %d\n", tmp->tm_hour);
            printf("    tm_mday  = %d\n", tmp->tm_mday);
            printf("    tm_mon   = %d\n", tmp->tm_mon);
            printf("    tm_year  = %d\n", tmp->tm_year);
            printf("    tm_wday  = %d\n", tmp->tm_wday);
            printf("    tm_yday  = %d\n", tmp->tm_yday);
            printf("    tm_isdst = %d\n", tmp->tm_isdst);
        }

        exit(EXIT_SUCCESS);
    }

関連項目
time(2), localtime(3), setlocale(3), strftime(3), strptime(3)

この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。