getdateのヘルプ・マニュアル
日本語 英語
getdate --help
man getdate
GETDATE(3) Linux Programmer’s Manual GETDATE(3)
名前
getdate, getdate_r - 日付と時刻の文字列を要素別の時刻に変換する
書式
#define _XOPEN_SOURCE 500
#include
struct tm *getdate(const char *string);
extern int getdate_err;
#define _GNU_SOURCE
#include
int getdate_r(const char *string, struct tm *res);
説明
getdate() 関数は、 string が指すバッファに格納された文字列表現の日付と
時刻を、要素別の時刻 (broken-down time) に変換する。要素別の時刻 は tm
構 造体に格納され、この構造体へのポインタが関数の結果として返される。こ
の tm 構造体は静的なメモリ領域にあり、 getdate() のそれ以降の呼び出しで
上書きされるかもされない。
(format 引 き 数でフォーマットを指定する) strptime(3) とは違い、 get-
date() は環境変数 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 経由で返され、 (get-
date_r() では) 関数の返り値として返される。
1 環境変数 DATEMASK が未定義、またはその値が空文字列である。
2 DATEMSK で指定されたテンプレートファイルを読み込み用にオープンで き
ない。
3 ファイルのステータス情報が取得できない。
4 テンプレートファイルが通常のファイルでない。
5 テンプレートファイルの読み込み中にエラーが起こった。
6 メモリの割り当てに失敗した (メモリが足りない)。
7 入力にマッチしたファイルに、行が含まれていない。
8 入力指定が正しくない。
環境変数
DATEMSK
書式パターンを含むファイル。
TZ, LC_TIME
strptime(3) が用いる変数。
準拠
POSIX.1-2001.
注意
POSIX.1-2001 仕様では、 strptime(3) については %E や %O といった修正子
を用いた変換指定を規定しているが、 getdate() についてはこのような修飾子
の規定はない。 glibc では、 getdate() は strptime(3) を用いて実装されて
おり、両者では全く同じ変換が両者でサポートされている。
例
以下のプログラムは、コマンドライン引き数のそれぞれについて getdate() を
呼 び出し、それぞれについて返された tm 構造体のフィールド値を表示する。
次のシェル・セッションは、プログラムの動作例である。
$ TFILE=$PWD/tfile
$ echo '%A' > $TFILE # Full weekday name
$ 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 500
#include
#include
#include
int
main(int argc, char *argv[])
{
struct tm *tmp;
int j;
for (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), fea-
ture_test_macros(7)
2008-09-07 GETDATE(3)
GETDATE(3) Linux Programmer’s Manual GETDATE(3)
NAME
getdate, getdate_r - convert a date-plus-time string to broken-down
time
SYNOPSIS
#define _XOPEN_SOURCE 500
#include
struct tm *getdate(const char *string);
extern int getdate_err;
#define _GNU_SOURCE
#include
int getdate_r(const char *string, struct tm *res);
DESCRIPTION
The function getdate() converts a string representation of a date and
time, contained in the buffer pointed to by string, into a broken-down
time. The broken-down time is stored in a tm structure, and a pointer
to this structure is returned as the function result. This tm struc-
ture is allocated in static storage, and consequently it will be over-
written by further calls to getdate().
In contrast to strptime(3), (which has a format argument), getdate()
uses the formats found in the file whose full pathname is given in the
environment variable DATEMSK. The first line in the file that matches
the given input string is used for the conversion.
The matching is done case insensitively. Superfluous whitespace,
either in the pattern or in the string to be converted, is ignored.
The conversion specifications that a pattern can contain are those
given for strptime(3). One more conversion specification is specified
in POSIX.1-2001:
%Z Timezone name. This is not implemented in glibc.
When %Z is given, the structure containing the broken-down time is ini-
tialized with values corresponding to the current time in the given
timezone. Otherwise, the structure is initialized to the broken-down
time corresponding to the current local time (as by a call to local-
time(3)).
When only the weekday is given, the day is taken to be the first such
day on or after today.
When only the month is given (and no year), the month is taken to be
the first such month equal to or after the current month. If no day is
given, it is the first day of the month.
When no hour, minute and second are given, the current hour, minute and
second are taken.
If no date is given, but we know the hour, then that hour is taken to
be the first such hour equal to or after the current hour.
getdate_r() is a GNU extension that provides a reentrant version of
getdate(). Rather than using a global variable to report errors and a
static buffer to return the broken down time, it returns errors via the
function result value, and returns the resulting broken-down time in
the caller-allocated buffer pointed to by the argument res.
RETURN VALUE
When successful, getdate() returns a pointer to a struct tm. Other-
wise, it returns NULL and sets the global variable getdate_err to one
of the error numbers shown below. Changes to errno are unspecified.
On success getdate_r() returns 0; on error it returns one of the error
numbers shown below.
ERRORS
The following errors are returned via getdate_err (for getdate()) or as
the function result (for getdate_r()):
1 The DATEMSK environment variable is not defined, or its value is an
empty string.
2 The template file specified by DATEMSK cannot be opened for read-
ing.
3 Failed to get file status information.
4 The template file is not a regular file.
5 An error was encountered while reading the template file.
6 Memory allocation failed (not enough memory available).
7 There is no line in the file that matches the input.
8 Invalid input specification.
ENVIRONMENT
DATEMSK
File containing format patterns.
TZ, LC_TIME
Variables used by strptime(3).
CONFORMING TO
POSIX.1-2001.
NOTES
The POSIX.1-2001 specification for strptime(3) contains conversion
specifications using the %E or %O modifier, while such specifications
are not given for getdate(). In glibc, getdate() is implemented using
strptime(3), so that precisely the same conversions are supported by
both.
EXAMPLE
The program below calls getdate() for each of its command-line argu-
ments, and for each call displays the values in the fields of the
returned tm structure. The following shell session demonstrates the
operation of the program:
$ TFILE=$PWD/tfile
$ echo '%A' > $TFILE # Full weekday name
$ 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
Program source
#define _GNU_SOURCE 500
#include
#include
#include
int
main(int argc, char *argv[])
{
struct tm *tmp;
int j;
for (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);
}
SEE ALSO
time(2), localtime(3), setlocale(3), strftime(3), strptime(3), fea-
ture_test_macros(7)
COLOPHON
This page is part of release 3.22 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
2008-09-07 GETDATE(3)