.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\" References consulted: .\" Linux libc source code .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" GNU texinfo documentation on glibc date/time functions. .\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith (faith@cs.unc.edu) .\" Applied fix by Wolfgang Franke, aeb, 961011 .\" Corrected return value, aeb, 970307 .\" Added Single UNIX Spec conversions and %z, aeb/esr, 990329. .\" 2005-11-22 mtk, added Glibc Notes covering optional 'flag' and .\" 'width' components of conversion specifications. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .\" .\" Japanese Version Copyright (c) 2000 HANATAKA Shinya .\" all rights reserved. .\" Translated 2000-10-10, HANATAKA Shinya .\" Updated 2002-01-09, Kentaro Shirakata .\" Updated 2002-01-14, Akihiro MOTOKI .\" Updated 2005-02-26, Akihiro MOTOKI .\" Updated 2005-04-17, Akihiro MOTOKI .\" Updated 2005-12-05, Akihiro MOTOKI, LDP v2.16 .\" Updated 2010-04-18, Akihiro MOTOKI, LDP v3.24 .\" Updated 2012-05-29, Akihiro MOTOKI .\" Updated 2013-03-26, Akihiro MOTOKI .\" Updated 2013-07-31, Akihiro MOTOKI .\" Updated 2021-04-13, Akihiro Motoki .\" .TH STRFTIME 3 " 2020\-08\-13" GNU "Linux Programmer's Manual" .SH 名前 strftime \- 日付および時刻の文字列への変換 .SH 書式 .nf \fB#include \fP .PP \fBsize_t strftime(char *\fP\fIs\fP\fB, size_t \fP\fImax\fP\fB, const char *\fP\fIformat\fP\fB,\fP \fB const struct tm *\fP\fItm\fP\fB);\fP .fi .SH 説明 .\" FIXME . POSIX says: Local timezone information is used as though .\" strftime() called tzset(). But this doesn't appear to be the case \fBstrftime\fP() 関数 は、要素別の時刻 \fItm\fP の内容を \fIformat\fP で指定された書式指定にしたがって変換し、長さ \fImax\fP の文字列 \fIs\fP に書き込む。要素別の時刻構造体 \fItm\fP は \fI\fP で定義されている。 \fBctime\fP(3) も参照。 .PP 書式指定はヌル終端された文字列であり、「変換指定 (conversion specification)」と呼ばれる特別な文字列を含めることができる。各々の変換指定は \(aq%\(aq 文字で始まり、「変換指定文字 (conversion specifier character)」と呼ばれる何らか他の文字で終端される。上記以外の全ての文字列は「通常の文字列 (ordinary character sequence)」となる。 .PP (NULL バイトも含む) 通常の文字列内の文字は、そのまま \fIformat\fP から \fIs\fP にコピーされる。一方、変換指定の文字は以下のリストに示すように置換される。このリストでは、 \fItm\fP 構造体のフィールドが参照される場合、その情報も記載している。 .TP \fB%a\fP 現在のロケールにおける曜日の省略名。 \fItm_wday\fP から計算される。現在のロケールで使用される具体的な名前は、引数に \fBABDAY_\fP{\fB1\fP\(en\fB7\fP} を指定して \fBnl_langinfo\fP(3) を呼び出すことで取得できる。 .TP \fB%A\fP 現在のロケールにおける曜日の完全な名前。 \fItm_wday\fP から計算される。現在のロケールで使用される具体的な名前は、引数に \fBDAY_\fP{\fB1\fP\(en\fB7\fP} を指定して \fBnl_langinfo\fP(3) を呼び出すことで取得できる。 .TP \fB%b\fP 現在のロケールにおける月の省略名。 \fItm_mon\fP から計算される。現在のロケールで使用される具体的な名前は、引数に \fBABMON_\fP{\fB1\fP\(en\fB12\fP} を指定して \fBnl_langinfo\fP(3) を呼び出すことで取得できる。 .TP \fB%B\fP 現在のロケールにおける月の完全な名前。 \fItm_mon\fP から計算される。現在のロケールで使用される具体的な名前は、引数に \fBMON_\fP{\fB1\fP\(en\fB12\fP} を指定して \fBnl_langinfo\fP(3) を呼び出すことで取得できる。 .TP \fB%c\fP 現在のロケールにおいて一般的な日付・時刻の表記。現在のロケールで使用される具体的なフォーマットは、 \fB%c\fP 変換指定の場合は \fBD_T_FMT\fP を、 \fB%Ec\fP 変換指定の場合は \fBERA_D_T_FMT\fP を引数に指定して \fBnl_langinfo\fP(3) を呼び出すことで取得できる。 POSIX ロケールでは \fB%a %b %e %H:%M:%S %Y\fP と等価である。 .TP \fB%C\fP 世紀に対応する 2 桁の整数 (year/1000)。 \fB%EC\fP 変換指定は、西暦以外の年数表記 ("era") の名前に対応する。 \fItm_year\fP から計算される。 (SU) .TP \fB%d\fP 月内通算日 (10 進数表記) (01\-31)。 \fItm_mday\fP から計算される。 .TP \fB%D\fP \fB%m/%d/%y\fP と等価。(うえっ、アメリカ専用だ。アメリカ以外の国では \fB%d/%m/%y\fP の方が一般的だ。紛らわしいので、使用すべきではない。) (SU) .TP \fB%e\fP \fB%d\fP と同様に月内通算日を 10 進数で表現するが、 1 桁の場合 10 の位にゼロを置かずスペースを置く。 \fItm_mday\fP から計算される。 (SU) .TP \fB%E\fP 別形式 (西暦以外の年数表記; "era") を使用する際の修飾子。下記参照。 (SU) .TP \fB%F\fP \fB%Y\-%m\-%d\fP と等価 (ISO\ 8601 形式の日付フォーマット)。 (C99) .TP \fB%G\fP ISO\ 8601 の週 (ISO\ 8601 week) に基づく年の表示。「注意」の節を参照)。世紀も 10 進数で表す。 ISO 週番号 (\fB%V\fP を参照) に対応した 4 桁の西暦年。 これは基本的には \fB%Y\fP と同じ形式だが、ISO 週数が前年や翌年になる場合にはその年が使用される点が異なる。 \fItm_year\fP, \fItm_yday\fP, \fItm_wday\fP から計算される。 (TZ) .TP \fB%g\fP \fB%G\fP と同様。ただし、世紀を含まず下 2 桁のみを表示 (00\(en99)。 \fItm_year\fP, \fItm_yday\fP, \fItm_wday\fP から計算される。 (TZ) .TP \fB%h\fP \fB%b\fP と等価 (SU) .TP \fB%H\fP 24 時間表記での時 (hour) (00\-23)。 \fItm_hour\fP から計算される。 .TP \fB%I\fP 12 時間表記での時 (hour) (01\-12)。 \fItm_hour\fP から計算される。 .TP \fB%j\fP 年の初めから通算の日数 (001\-366)。 \fItm_yday\fP から計算される。 .TP \fB%k\fP 24 時間表記での時 (0\-23)。 1 桁の場合には前にゼロでなくスペースが置かれる。 \fB%H\fP も参照。 \fItm_hour\fP から計算される。 (TZ) .TP \fB%l\fP 12 時間表記での時 (0\-12)。 1 桁の場合には前にゼロでなくスペースが置かれる。 \fB%I\fP も参照。 \fItm_hour\fP から計算される。 (TZ) .TP \fB%m\fP 10 進数表記の月 (01\-12)。 \fItm_mon\fP から計算される。 .TP \fB%M\fP 10 進数表記の分 (00\-59)。 \fItm_min\fP から計算される。 .TP \fB%n\fP 改行 (SU) .TP \fB%O\fP 別の数値シンボルを使用する際の修飾子。下記参照。 (SU) .TP \fB%p\fP 現在のロケールにおける「午前」「午後」に相当する文字列。 英語の場合には "AM" または "PM" となる。 正午は「午後」、真夜中は「午前」として扱われる。 \fItm_hour\fP から計算される。現在のロケールで "AM" と "PM" に対応する文字列表現は、それぞれ \fBAM_STR\fP と \fBPM_STR\fP を指定して \fBnl_langinfo\fP(3) を呼び出すことで取得できる。 .TP \fB%P\fP \fB%p\fP と同様であるが小文字が使用される。 "am" や "pm"、もしくは現在のロケールでの対応する文字列となる。 \fItm_hour\fP から計算される。 (GNU) .TP \fB%r\fP 午前・午後形式での時刻。現在のロケールで使用される具体的なフォーマットは、引数に \fBT_FMT_AMPM\fP を指定して \fBnl_langinfo\fP(3) を呼び出すことで取得できる。 POSIX ロケールでは \fB%I:%M:%S %p\fP と等価である。 (SU) .TP \fB%R\fP 24 時間表記での時刻、秒は表示しない (\fB%H:%M\fP)。 秒を含んだものは以下の \fB%T\fP を参照すること。(SU) .TP \fB%s\fP 紀元 (Epoch; 1970\-01\-01 00:00:00 +0000 (UTC)) からの秒数。 \fImktime(tm)\fP から計算される。 (TZ) .TP \fB%S\fP 秒 (10 進数表記) (00\-60)。時々ある閏秒に対応するため、値の範囲は 60 までとなっている。 \fItm_sec\fP から計算される。 .TP \fB%t\fP タブ文字 (SU) .TP \fB%T\fP 24 時間表記の時間 (\fB%H:%M:%S\fP) (SU) .TP \fB%u\fP 週の何番目の日 (10 進数表記) か。月曜日を 1 とする (1\-7)。 \fB%w\fP も参照。 \fItm_wday\fP から計算される。 (SU) .TP \fB%U\fP 年の初めからの通算の週番号 (10 進数表記) (00\-53)。 その年の最初の日曜日を、第 1 週の始まりとして計算する。 \fB%V\fP と \fB%W\fP も参照すること。 \fItm_yday\fP と \fItm_wday\fP から計算される。 .TP \fB%V\fP ISO\ 8601 形式での年の始めからの週番号 (「注意」の節を参照)。 10 進数表記で、01 から 53 の値となる。週番号は、新しい年が少なくとも 4 日以上含まれる最初の週を 1 として計算する。 \fB%U\fP と \fB%W\fP も参照のこと。 \fItm_year\fP, \fItm_yday\fP, \fItm_wday\fP から計算される。 (SU) .TP \fB%w\fP 週の何番目の日 (10 進数表記) か。日曜日を 0 とする。(0\-6)。 \fB%u\fP も参照。 \fItm_wday\fP から計算される。 .TP \fB%W\fP 年の初めからの通算の週番号 (10 進数表記) (00\-53)。 その年の最初の月曜日を、第 1 週の始まりとして計算する。 \fB%V\fP と \fB%W\fP も参照すること。 \fItm_yday\fP と \fItm_wday\fP から計算される。 .TP \fB%x\fP 現在のロケールで一般的な日付表記。時刻は含まない。現在のロケールで使用される具体的なフォーマットは、 \fB%x\fP 変換指定の場合は \fBD_FMT\fP を、 \fB%Ex\fP 変換指定の場合は \fBERA_D_FMT\fP を引数に指定して、 \fBnl_langinfo\fP(3) を呼び出すことで取得できる。 POSIX ロケールでは、これは \fB%m/%d/%y\fP と等価である。 .TP \fB%X\fP 現在のロケールで一般的な時刻表記。日付は含まない。現在のロケールで使用される具体的なフォーマットは、 \fB%X\fP 変換指定の場合は \fBT_FMT\fP を、 \fB%EX\fP 変換指定の場合は \fBERA_T_FMT\fP を引数に指定して、 \fBnl_langinfo\fP(3) を呼び出すことで取得できる。 POSIX ロケールでは、これは \fB%H:%M:%S\fP と等価である。 .TP \fB%y\fP 西暦の下 2 桁 (世紀部分を含まない年) (00 から 99)。 \fB%Ey\fP 変換指定は。 \fB%EC\fP 変換指定で示される西暦以外の年数表記 ("era") における初めからの年数に対応する。 \fItm_year\fP から計算される。 .TP \fB%Y\fP 世紀部分を含めた 10 進表記の西暦年。 \fB%EY\fP 変換指定は別形式の年表記の完全な表現に対応する。 \fItm_year\fP から計算される。 .TP \fB%z\fP \fI+hhmm\fP や \fI\-hhmm\fP の形式のタイムゾーン (UTC へのオフセット時間)。(SU) .TP \fB%Z\fP タイムゾーン名または省略名。 .TP \fB%+\fP .\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to .\" their man pages) \fBdate\fP(1) 形式での日時。 glibc2 ではサポートされていない。 (TZ) .TP \fB%%\fP \(aq%\(aq 文字 .PP いくつかの変換指定では、変換指定文字の前に \fBE\fP や \fBO\fP 「修飾子」を置くことによって別書式を使用するように指定することができる。 現在のロケールにおいて別書式が存在しない場合には、 通常の変換指定が使用されたかのように動作する (SU)。 統一 UNIX 規格 (Single UNIX Specification) では \fB%Ec\fP, \fB%EC\fP, \fB%Ex\fP, \fB%EX\fP, \fB%Ey\fP, \fB%EY\fP, \fB%Od\fP, \fB%Oe\fP, \fB%OH\fP, \fB%OI\fP, \fB%Om\fP, \fB%OM\fP, \fB%OS\fP, \fB%Ou\fP, \fB%OU\fP, \fB%OV\fP, \fB%Ow\fP, \fB%OW\fP, \fB%Oy\fP, について記述がある。ここで \fBO\fP 修飾子は別形式の数値シンボル (ローマ数字とか) を指定するために使用する。 \fBE\fP 修飾子はロケール依存の別表現を指定するのに使用する。 \fBE\fP 修飾子を使った場合のデータ表現に適用されるルールは、 \fBnl_langinfo\fP(3) の引数に \fBERA\fP を指定することで取得できる。このような別表現の例としては \fBja_JP\fP glibc ロケールでの日本の年号 (「昭和」「平成」など) によるカレンダー表記がある。 .SH 返り値 .\" (This behavior applies since at least libc 4.4.4; .\" very old versions of libc, such as libc 4.4.1, .\" would return .\" .I max .\" if the array was too small.) 終端のヌルバイトを含めた結果の文字列の長さが \fImax\fP バイトを超えなかった場合、 \fBstrftime\fP() 関数は配列 \fIs\fP に格納されたバイト数を返す (このバイト数に終端のヌルバイトは含まれない)。 終端のヌルバイトを含めた結果の文字列の長さが \fImax\fP バイトを超える場合には、 \fBstrftime\fP() は 0 を返し、配列の内容は不定となる。 .PP 返り値 0 は必ずしもエラーを意味している訳ではないので注意すること。例えば、多くのロケールでは \fB%p\fP は空文字列を返す。同様に、空の \fIformat\fP 文字列は空文字列を返す。 .SH 環境変数 環境変数 \fBTZ\fP と \fBLC_TIME\fP が使用される。 (訳注: \fBLC_ALL\fP が設定されている場合には \fBLC_TIME\fP よりもそちらが優先される。 \fBLC_TIME\fP も \fBLC_ALL\fP も設定されていない場合には \fBLANG\fP が使用される。) .SH 属性 この節で使用されている用語の説明については、 \fBattributes\fP(7) を参照。 .TS allbox; lb lb lb l l l. インターフェース 属性 値 T{ \fBstrftime\fP() T} Thread safety MT\-Safe env locale .TE .SH 準拠 .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details .\" in the standards changed across versions. Investigate and .\" write up. SVr4, C89, C99. 個々の変換が厳密にどの規格に含まれるかをマークで示している。「マークなし」は ANSI C、「SU」は統一 UNIX 規格を、「TZ」は Olson の timezone パッケージ、「GNU」は glibc を示す。 glibc2 では \fB%+\fP はサポートされていないが、 いくつかの拡張が行われている。POSIX.1 では ANSI C のみを参照している。 POSIX.2 の \fBdate\fP(1) のところに記述されている幾つかの拡張は \fBstrftime\fP() にも適用できるだろう。 \fB%F\fP 変換は C99 と POSIX.1\-2001 にある。 .PP SUSv2 では、 \fB%S\fP は 00 から 61 の範囲をとると規定されている。 これは、1 分間のうち閏秒が 2 つ入る可能性が理論的にはあることを考慮してのものである (実際には、このような状況はこれまで一度も 起こっていない)。 .SH 注意 .SS "ISO\ 8601 の暦週日付" \fB%G\fP, \fB%g\fP, \fB%V\fP は、ISO\ 8601 標準により定義された週単位表記の年により 計算される値を出力する。 ISO\ 8601 標準の週単位表記では、週は月曜日から開始され、 週番号は、年の最初の週が 01 となり、最後の週は 52 か 53 となる。 週 01 は、新しい年が 4 日以上含まれる最初の週である。 言い換えると、週 01 は、その年の木曜日を含む最初の週、 つまり 1 月 4 日を含む週ということである。 新しい年のカレンダー上の最初の週に新しい年が 3 日以下しか含まれない場合、 ISO\ 8601 の週単位表記では、これらの日を前の年の週 53 の一部とみなす。 例えば、2010 年 1 月 1 日は金曜日であり、 その週には 2010 年の日が 3 日しか含まれない。 したがって、ISO\ 8601 の週単位表記では、これらの日は 2009 年 (\fB%G\fP) の週 53 (\fB%V\fP) の一部となる。 ISO\ 8601 の 2010 年の週 01 は 2010 年 1 月 4 日の月曜日から始まる。同様に、 2011 年 1 月の最初の 2 日は 2010 年の週 52 の一部とみなされる。 .SS "glibc での注意" .\" HP-UX and Tru64 also have features like this. glibc では変換指定にいくつか拡張を行っている (これらの拡張は POSIX.1\-2001 には規定されていないが、 他のいくつかのシステムで同様の機能が提供されている)。 \(aq%\(aq 文字と変換指定文字の間に、オプションとして \fIフラグ\fP とフィールドの \fI幅\fP を指定できる (これらを指定する場合には \fBE\fP や \fBO\fP 修飾子の前に置く)。 .PP 以下のフラグ文字が使用できる。 .TP \fB_\fP (下線) 数値の結果文字列のパディング (穴埋め) をスペース (空白文字) で行う。 .TP \fB\-\fP (ダッシュ) 数値の結果文字列に対するパディングを行わない。 .TP \fB0\fP 変換指定文字がデフォルトではスペースでパディングを行う場合でも、 数値の結果文字列へのパディングを 0 で行う。 .TP \fB\(ha\fP 結果文字列中のアルファベット文字を大文字に変換する。 .TP \fB#\fP 結果文字列の大文字・小文字を入れ替える (このフラグは特定の変換指定文字でしか機能しない。その中でも 本当に有用なのは \fB%Z\fP の場合だけである)。 .PP オプションの 10 進数の幅指定子はフラグの後ろに置くことができる (フラグはなくてもよい)。フィールドの本来の大きさが指定された幅よりも 小さい場合、結果文字列の左側は指定された幅までパディングされる。 .SH バグ 出力文字列が \fImax\fP バイトを超えてしまう場合、 \fIerrno\fP は設定「されない」。 このため、このエラーと、 \fIformat\fP 文字列がきちんと処理されて長さ 0 の出力文字列が生成される場合、を区別することができない。 POSIX.1\-2001 では \fBstrftime\fP() に関して \fIerrno\fP に設定される値について一切規定して「いない」。 .PP \fBgcc\fP(1) のいくつかのバージョンにはおかしなところがあり、 \fB%c\fP の使用法について以下のような警告を出す: \fIwarning: `%c\(aq yields only last 2 digits of year in some locales\fP (\fI警告:\fP いくつかのロケールでは \fI`%c\(aq\fP は年の下2桁しか出力しない\fI)。\fP もちろんプログラマが \fB%c\fP を使うのはお薦めできることである。 \fB%c\fP を使うと適切な日付と時刻の表記を得ることができるからである。 \fBgcc\fP(1) のこの問題を回避しようとすると、何かすっきりしない気分になるだろう。 比較的きれいな回避策は以下のような中間関数を追加することである。 .PP .in +4n .EX size_t my_strftime(char *s, size_t max, const char *fmt, const struct tm *tm) { return strftime(s, max, fmt, tm); } .EE .in .PP 現在では、 \fBgcc\fP(1) はこの警告を抑えるための \fI\-Wno\-format\-y2k\fP オプションを 提供しており、上記の回避策はもはや必要ない。 .SH 例 \fBRFC\ 2822 準拠の日付形式\fP (%a と %b は英語ロケール) .PP .in +4n .EX "%a,\ %d\ %b\ %Y\ %T\ %z" .EE .in .PP \fBRFC\ 822 準拠の日付形式\fP (%a と %b は英語ロケール) .PP .in +4n .EX "%a,\ %d\ %b\ %y\ %T\ %z" .EE .in .SS サンプルプログラム 以下のプログラムを使うと \fBstrftime\fP() の実験ができる。 .PP 以下に \fBstrftime\fP() の glibc 実装が生成する結果の例をいくつか示す。 .PP .in +4n .EX $\fB ./a.out \(aq%m\(aq\fP Result string is "11" $\fB ./a.out \(aq%5m\(aq\fP Result string is "00011" $\fB ./a.out \(aq%_5m\(aq\fP Result string is " 11" .EE .in .SS プログラムのソース \& .EX #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 \e"%s\e"\en", outstr); exit(EXIT_SUCCESS); } .EE .SH 関連項目 \fBdate\fP(1), \fBtime\fP(2), \fBctime\fP(3), \fBnl_langinfo\fP(3), \fBsetlocale\fP(3), \fBsprintf\fP(3), \fBstrptime\fP(3) .SH この文書について この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は \%https://www.kernel.org/doc/man\-pages/ に書かれている。