strftimeのヘルプ・マニュアル
日本語 英語
strftime --help
man strftime
STRFTIME(3) Linux Programmer’s Manual STRFTIME(3)
名前
strftime - 日付および時刻の文字列への変換
書式
#include
size_t strftime(char *s, size_t max, const char *format,
const struct tm *tm);
説明
strftime() 関数 は、要素別の時刻 tm の内容を format で指定された書式指
定にしたがって変換し、長さ max の文字列 s に書き込む。
書式文字列に含まれる通常の文字は変換されずそのまま文字列 s にコピーされ
る。「変換指定」は '%' 文字で始まり、「変換指定文字」で終端される。以下
のように変換されて s に格納される:
%a 現在のロケールにおける曜日の省略名。
%A 現在のロケールにおける曜日の完全な名前。
%b 現在のロケールにおける月の省略名。
%B 現在のロケールにおける月の完全な名前。
%c 現在のロケールにおいて一般的な日付・時刻の表記。
%C 世紀 (西暦年の上 2 桁)。 (SU)
%d 月内通算日 (10 進数表記) (01-31)。
%D %m/%d/%y と等価。(うえっ、アメリカ専用だ。アメリカ以外の国 で は
%d/%m/%y の方が一般的だ。紛らわしいので、使用すべきではない。)
(SU)
%e %d と同様に月内通算日を 10 進数で表現するが、 1 桁の場合 10 の位
にゼロを置かずスペースを置く。(SU)
%E 別形式を使用する際の修飾子。下記参照。 (SU)
%F %Y-%m-%d と等価 (ISO 8601 形式の日付フォーマット)。 (C99)
%G ISO 8601 形式の年 (世紀も 10 進数で表す)。 ISO 週数 (%V を参照)
に対応した 4 桁の西暦年。これは基本的には %y と同じ形式だが、ISO
週数が前年や翌年になる場合にはその年が使用される。(TZ)
%g %G と同様。但し、世紀を含まず下 2 桁のみを表示 (00-99)。 (TZ)
%h %b と等価 (SU)
%H 24 時間表記での時 (hour)。 (00-23)
%I 12 時間表記での時 (hour)。 (01-12)
%j 年の初めから通算の日数。 (001-366)
%k 24 時間表記での時 (0-23)。 1 桁の場合には前にゼロでなくスペース
が置かれる。 (%H も参照) (TZ)
%l 12 時間表記での時 (0-12)。 1 桁の場合には前にゼロでなくスペー ス
が置かれる。 (%I も参照) (TZ)
%m 月 (10 進数表記)。 (01-12)
%M 分 (10 進数表記) (00-59)
%n 改行。 (SU)
%O 別形式を使用する際の修飾子。以下を参照。(SU)
%p 現在のロケールにおける「午前」「午後」に相当する文字列。英語の場
合には "AM" または "PM" となる。正午は「午後」、真夜中は「午前」
として扱われる。
%P %p と同様であるが小文字が使用される。英語の場合には "am" や "pm"
となる。(GNU)
%r 午前・午後形式での時刻。 POSIX ロケールでは %I:%M:%S %p と等価で
ある。(SU)
%R 24 時間表記での時刻、秒は表示しない (%H:%M)。秒を含んだものは以
下の %T を参照すること。(SU)
%s 紀元 (1970年 1 月 1 日 00:00:00 UTC) からの秒数。 (TZ)
%S 秒 (10 進数表記) (00-60) (時々ある閏秒に対応するため、値の範囲は
60 までとなっている)
%t タブ文字 (SU)
%T 24 時間表記の時間 (%H:%M:%S) (SU)
%u 週の何番目の日 (10 進数表記) か。月曜日を 1 とする (1-7)。 %w も
参照。(SU)
%U 年の初めからの通算の週数 (10 進数表記) (00-53)。その年の最初の日
曜 日を、第 1 週の始まりとして計算する。 %V と %W も参照すること
。
%V ISO 8601:1988 形式での年の始めからの週数 (10 進数表記) (00-53)。
その年に少なくとも 4 日以上含まれる最初の週を 1 として計算する。
週の始まりは月曜日とする。 %U と %W も参照すること。
%w 週の何番目の日 (10 進数表記) か。日曜日を 0 とする。(0-6) 。 %u
も参照。(SU)
%W 年の初めからの通算の週数 (10 進数表記) (00-53)。その年の最初の月
曜日を、第 1 週の始まりとして計算する。
%x 現在のロケールで一般的な日付表記。時刻は含まない。
%X 現在のロケールで一般的な時刻表記。日付は含まない。
%y 西暦の下2桁 (世紀部分を含まない年) (00-99)。
%Y 世紀部分を含めた ( 4 桁の) 西暦年。
%z タイムゾーンの GMT へのオフセット時間。 RFC 822 形式の日時に必要
である。 ("%a, %d %b %Y %H:%M:%S %z" として使用する)。(GNU)
%Z タイムゾーンまたはゾーン名または省略名。
%+ date(1) 形式での日時。(TZ) (glibc2 ではサポートされていない)
%% '%' 文字。
い くつかの変換指定では、変換指定文字の前に E や O 「修飾子」を置くこと
によって別書式を使用するように指定することができる。現在のロケールに お
い て別書式が存在しない場合には、通常の変換指定が使用されたかのように動
作する (SU)。統一 UNIX 規格 (Single Unix Specification) では %Ec, %EC,
%Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV,
%Ow, %OW, %Oy, について記述がある。ここで O 修飾子は別形式の数値 (ロ ー
マ数字とか) を指定するために使用する。 E 修飾子はロケール依存の別表現を
指定するのに使用する。 (訳注: E 修飾子は日本で使用されている「昭和」 「
平成」などの元号による年表記を指定する。glibc 2.2 以降でのみ有効)
要 素別の時刻構造体 tm の詳細は に定義されている。 ctime(3) も
参照すること。
返り値
strftime() 関数は文字列 s に格納された文字数を返す。この文字数に終端 の
NULL バイトは含まない。終端の NULL バイトを格納できるだけの大きさを持っ
た文字列を渡すこと。それ以外の場合は 0 を返し、文字列の内容は修正されな
い。 (libc 4.4.4 以降でこの挙動が適用されている。 libc 4.4.1 などの非常
に古いバージョンの libc では文字列が短か過ぎた場合には max が返さ れ る
。)
返り値 0 は必ずしもエラーを意味している訳ではないので注意すること。例え
ば、多くのロケールでは %p は空文字列を返す。
環境変数
環境変数 TZ と LC_TIME が使用される。 (訳注: LC_ALL が設定されている 場
合 には LC_TIME よりもそちらが優先される。 LC_TIME も LC_ALL も設定され
ていない場合には LANG が使用される。)
準拠
SVr4, C89, C99. 個々の変換が厳密にどの規格に含まれるかは、 ANSI C ( 印
な し) 、 統 一 UNIX 規格 (SU印)、Olson の timezone パッケージ (TZ印)、
glibc 独自 (GNU印) で示している。glibc2 では %+ はサポートされていな い
が 、いくつかの拡張が行われている。POSIX.1 では ANSI C のみを参照してい
る。 POSIX.2 の date(1) のところに記述されている幾つかの拡 張 は strf-
time() にも適用できるだろう。 %F 変換は C99 と POSIX.1-2001 にある。
SUSv2 では、 %S は 00 から 61 の範囲をとると規定されている。これは、1分
間のうち閏秒が 2つ入る可能性が理論的にはあることを考慮してのものであ る
(実際には、このような状況はこれまで一度も起こっていない)。
注意
glibc での注意
glibc で は 変 換 指 定 に い く つか拡張を行っている (これらの拡張は
POSIX.1-2001 には規定されていないが、他のいくつかのシステムで同様の機能
が提供されている)。 '%' 文字と変換指定文字の間に、オプションとして flag
とフィールドの 幅を指定できる (これらを指定する場合には E や O 修飾子の
前に置く)。
以下のフラグ文字が使用できる:
_ ( 下線) 数値の結果文字列のパディング (穴埋め) をスペース (空白文
字) で行う。
- (ダッシュ) 数値の結果文字列に対するパディングを行わない。
0 変換指定文字がデフォルトではスペースでパディングを行う場合でも、
数値の結果文字列へのパディングを 0 で行う。
^ 結果文字列中のアルファベット文字を大文字に変換する。
# 結果文字列の大文字・小文字を入れ替える (このフラグは特定の変換指
定文字でしか機能しない。その中でも本当に有用なのは %Z の場合だけ
である)。
オ プションの10進数の幅指定子はフラグの後ろに置くことができる (フラグは
なくてもよい)。フィールドの本来の大きさが指定された幅よりも小さい場合、
結果文字列の左側は指定された幅までパディングされる。
バグ
gcc(1) のいくつかのバージョンにはおかしなところがあり、 %c の使用法につ
いて以下のような警告を出す: warning: ‘%c’ yields only last 2 digits of
year in some locales (警告:いくつかのロケールでは‘%c’は年の下2桁しか出
力しない)。もちろんプログラマが %c を使うのはお薦めできることであ る 。
%c を使うと適切な日付と時刻の表記を得ることができるからである。 gcc(1)
のこの問題を回避しようとすると、何かすっきりしない気分になるだろう。 比
較的きれいな解決方法は以下のような中間関数を追加することである。
size_t
my_strftime(char *s, size_t max, const char *fmt,
const struct tm *tm)
{
return strftime(s, max, fmt, tm);
}
現 在では、 gcc(1) はこの警告を抑えるための -Wno-format-y2k オプションを提供し
ており、上記の回避策はもはや必要ない。
例
以下のプログラムを使うと strftime() の実験ができる。
以下に、 strftime() の glibc 実装が生成する結果の例をいくつか示す:
$ ./a.out '%m'
Result string is "11"
$ ./a.out '%5m'
Result string is "00011"
$ ./a.out '%_5m'
Result string is " 11"
プログラムのソース
#include
#include
#include
int
main(int argc, char *argv[])
{
char outstr[200];
以下に、
strftime()
の glibc 実装が生成する結果の例をいくつか示す:
$ ./a.out "%m"
Result string is "11"
$ ./a.out "%5m"
Result string is "00011"
$ ./a.out "%_5m"
Result string is " 11"
time_t t;
struct tm *tmp;
t = time(NULL);
tmp = localtime(&t);
if (tmp == NULL) {
perror("localtime");
exit(EXIT_FAILURE);
}
if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
fprintf(stderr, "strftime returned 0");
exit(EXIT_FAILURE);
}
printf("Result string is \"%s\"\n", outstr);
exit(EXIT_SUCCESS); } /* main */
関連項目
date(1), time(2), ctime(3), setlocale(3), sprintf(3), strptime(3)
GNU 2008-10-29 STRFTIME(3)
STRFTIME(3) Linux Programmer’s Manual STRFTIME(3)
NAME
strftime - format date and time
SYNOPSIS
#include
size_t strftime(char *s, size_t max, const char *format,
const struct tm *tm);
DESCRIPTION
The strftime() function formats the broken-down time tm according to
the format specification format and places the result in the character
array s of size max.
Ordinary characters placed in the format string are copied to s without
conversion. Conversion specifications are introduced by a '%' charac-
ter, and terminated by a conversion specifier character, and are
replaced in s as follows:
%a The abbreviated weekday name according to the current locale.
%A The full weekday name according to the current locale.
%b The abbreviated month name according to the current locale.
%B The full month name according to the current locale.
%c The preferred date and time representation for the current
locale.
%C The century number (year/100) as a 2-digit integer. (SU)
%d The day of the month as a decimal number (range 01 to 31).
%D Equivalent to %m/%d/%y. (Yecch — for Americans only. Americans
should note that in other countries %d/%m/%y is rather common.
This means that in international context this format is ambigu-
ous and should not be used.) (SU)
%e Like %d, the day of the month as a decimal number, but a leading
zero is replaced by a space. (SU)
%E Modifier: use alternative format, see below. (SU)
%F Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)
%G The ISO 8601 week-based year (see NOTES) with century as a deci-
mal number. The 4-digit year corresponding to the ISO week num-
ber (see %V). This has the same format and value as %Y, except
that if the ISO week number belongs to the previous or next
year, that year is used instead. (TZ)
%g Like %G, but without century, that is, with a 2-digit year
(00-99). (TZ)
%h Equivalent to %b. (SU)
%H The hour as a decimal number using a 24-hour clock (range 00 to
23).
%I The hour as a decimal number using a 12-hour clock (range 01 to
12).
%j The day of the year as a decimal number (range 001 to 366).
%k The hour (24-hour clock) as a decimal number (range 0 to 23);
single digits are preceded by a blank. (See also %H.) (TZ)
%l The hour (12-hour clock) as a decimal number (range 1 to 12);
single digits are preceded by a blank. (See also %I.) (TZ)
%m The month as a decimal number (range 01 to 12).
%M The minute as a decimal number (range 00 to 59).
%n A newline character. (SU)
%O Modifier: use alternative format, see below. (SU)
%p Either "AM" or "PM" according to the given time value, or the
corresponding strings for the current locale. Noon is treated
as "PM" and midnight as "AM".
%P Like %p but in lowercase: "am" or "pm" or a corresponding string
for the current locale. (GNU)
%r The time in a.m. or p.m. notation. In the POSIX locale this is
equivalent to %I:%M:%S %p. (SU)
%R The time in 24-hour notation (%H:%M). (SU) For a version includ-
ing the seconds, see %T below.
%s The number of seconds since the Epoch, that is, since 1970-01-01
00:00:00 UTC. (TZ)
%S The second as a decimal number (range 00 to 60). (The range is
up to 60 to allow for occasional leap seconds.)
%t A tab character. (SU)
%T The time in 24-hour notation (%H:%M:%S). (SU)
%u The day of the week as a decimal, range 1 to 7, Monday being 1.
See also %w. (SU)
%U The week number of the current year as a decimal number, range
00 to 53, starting with the first Sunday as the first day of
week 01. See also %V and %W.
%V The ISO 8601 week number (see NOTES) of the current year as a
decimal number, range 01 to 53, where week 1 is the first week
that has at least 4 days in the new year. See also %U and %W.
(SU)
%w The day of the week as a decimal, range 0 to 6, Sunday being 0.
See also %u.
%W The week number of the current year as a decimal number, range
00 to 53, starting with the first Monday as the first day of
week 01.
%x The preferred date representation for the current locale without
the time.
%X The preferred time representation for the current locale without
the date.
%y The year as a decimal number without a century (range 00 to 99).
%Y The year as a decimal number including the century.
%z The time-zone as hour offset from GMT. Required to emit
RFC 822-conformant dates (using "%a, %d %b %Y %H:%M:%S %z").
(GNU)
%Z The timezone or name or abbreviation.
%+ The date and time in date(1) format. (TZ) (Not supported in
glibc2.)
%% A literal '%' character.
Some conversion specifications can be modified by preceding the conver-
sion specifier character by the E or O modifier to indicate that an
alternative format should be used. If the alternative format or speci-
fication does not exist for the current locale, the behavior will be as
if the unmodified conversion specification were used. (SU) The Single
Unix Specification mentions %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe,
%OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect
of the O modifier is to use alternative numeric symbols (say, roman
numerals), and that of the E modifier is to use a locale-dependent
alternative representation.
The broken-down time structure tm is defined in . See also
ctime(3).
RETURN VALUE
The strftime() function returns the number of characters placed in the
array s, not including the terminating null byte, provided the string,
including the terminating null byte, fits. Otherwise, it returns 0,
and the contents of the array is undefined. (This behavior applies
since at least libc 4.4.4; very old versions of libc, such as libc
4.4.1, would return max if the array was too small.)
Note that the return value 0 does not necessarily indicate an error;
for example, in many locales %p yields an empty string.
ENVIRONMENT
The environment variables TZ and LC_TIME are used.
CONFORMING TO
SVr4, C89, C99. There are strict inclusions between the set of conver-
sions given in ANSI C (unmarked), those given in the Single Unix Speci-
fication (marked SU), those given in Olson’s timezone package (marked
TZ), and those given in glibc (marked GNU), except that %+ is not sup-
ported in glibc2. On the other hand glibc2 has several more exten-
sions. POSIX.1 only refers to ANSI C; POSIX.2 describes under date(1)
several extensions that could apply to strftime() as well. The %F con-
version is in C99 and POSIX.1-2001.
In SUSv2, the %S specifier allowed a range of 00 to 61, to allow for
the theoretical possibility of a minute that included a double leap
second (there never has been such a minute).
NOTES
ISO 8601 Week Dates
%G, %g, and %V yield values calculated from the week-based year defined
by the ISO 8601 standard. In this system, weeks start on a Monday, and
are numbered from 01, for the first week, up to 52 or 53, for the last
week. Week 1 is the first week where four or more days fall within the
new year (or, synonymously, week 01 is: the first week of the year that
contains a Thursday; or, the week that has 4 January in it). When
three of fewer days of the first calendar week of the new year fall
within that year, then the ISO 8601 week-based system counts those days
as part of week 53 of the preceding year. For example, 1 January 2010
is a Friday, meaning that just three days of that calendar week fall in
2010. Thus, the ISO 8601 week-based system considers these days to be
part of week 53 (%V) of the year 2009 (%G) ; week 01 of ISO 8601 year
2010 starts on Thursday, 4 January 2010.
Glibc Notes
Glibc provides some extensions for conversion specifications. (These
extensions are not specified in POSIX.1-2001, but a few other systems
provide similar features.) Between the '%' character and the conver-
sion specifier character, an optional flag and field width may be spec-
ified. (These precede the E or O modifiers, if present.)
The following flag characters are permitted:
_ (underscore) Pad a numeric result string with spaces.
- (dash) Do not pad a numeric result string.
0 Pad a numeric result string with zeros even if the conversion
specifier character uses space-padding by default.
^ Convert alphabetic characters in result string to upper case.
# Swap the case of the result string. (This flag only works with
certain conversion specifier characters, and of these, it is
only really useful with %Z.)
An optional decimal width specifier may follow the (possibly absent)
flag. If the natural size of the field is smaller than this width,
then the result string is padded (on the left) to the specified width.
BUGS
Some buggy versions of gcc(1) complain about the use of %c: warning:
‘%c’ yields only last 2 digits of year in some locales. Of course pro-
grammers are encouraged to use %c, it gives the preferred date and time
representation. One meets all kinds of strange obfuscations to circum-
vent this gcc(1) problem. A relatively clean one is to add an interme-
diate function
size_t
my_strftime(char *s, size_t max, const char *fmt,
const struct tm *tm)
{
return strftime(s, max, fmt, tm);
}
Nowadays, gcc(1) provides the -Wno-format-y2k option to prevent the
warning, so that the above workaround is no longer required.
EXAMPLE
The program below can be used to experiment with strftime().
Some examples of the result string produced by the glibc implementation
of strftime() are as follows:
$ ./a.out '%m'
Result string is "11"
$ ./a.out '%5m'
Result string is "00011"
$ ./a.out '%_5m'
Result string is " 11"
Program source
#include
#include
#include
int
main(int argc, char *argv[])
{
char outstr[200];
time_t t;
struct tm *tmp;
t = time(NULL);
tmp = localtime(&t);
if (tmp == NULL) {
perror("localtime");
exit(EXIT_FAILURE);
}
if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
fprintf(stderr, "strftime returned 0");
exit(EXIT_FAILURE);
}
printf("Result string is \"%s\"\n", outstr);
exit(EXIT_SUCCESS);
} /* main */
SEE ALSO
date(1), time(2), ctime(3), setlocale(3), sprintf(3), strptime(3)
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/.
GNU 2009-02-24 STRFTIME(3)