getdate

Section: C Library Functions (3)
Updated: 2026-02-08
Index JM Home Page

名前

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

ライブラリ

標準 C ライブラリ (libc, -lc)

書式

#include <time.h>

struct tm *getdate(const char *string);

extern int getdate_err;

int getdate_r(const char *restrict string, struct tm *restrict 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 仕様では、 strptime(3) については %E や %O といった修正子を用いた変換指定を規定していますが、 getdate() についてはこのような修飾子の規定はありません。glibc では、 getdate() は strptime(3) を用いて実装されており、両者では全く同じ変換が両者でサポートされています。

標準

POSIX.1-2008.

履歴

POSIX.1-2001.

例

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

$ TFILE=$PWD/tfile $ echo '%A' > $TFILE # Full name of the day of the week $ echo '%T' >> $TFILE # Time (HH:MM:SS) $ echo '%F' >> $TFILE # ISO date (YYYY-MM-DD) $ 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 <stdio.h> #include <stdlib.h> #include <time.h> int main(int argc, char *argv[]) {
    struct tm *tmp;
    for (size_t j = 1; j < argc; j++) {
        tmp = getdate(argv[j]);
        if (tmp == NULL) {
            printf("Call %zu failed; getdate_err = %d\n",
                   j, getdate_err);
            continue;
        }
        printf("Call %zu (\"%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); }