Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all bug

名前

       strftime - 日付および時刻の文字列への変換

書式

       #include <time.h>

       size_t strftime(char *s, size_t max, const char *format,
                       const struct tm *tm);

説明

       strftime()  関数  は、要素別の時刻 tm の内容を format で指定された書式指定にしたがって変換
       し、長さ max の文字列 s に書き込む。要素別の時刻構造体 tm<time.h>  で定義されている。
       ctime(3) も参照。

       書式指定はヌル終端された文字列であり、「変換指定  (conversion specification)」と呼ばれる特
       別な文字列を含めることができる。各々の変換指定は     '%'      文字で始まり、「変換指定文字
       (conversion specifier character)」と呼ばれる何らか他の文字で終端される。上記以外の全ての文
       字列は「通常の文字列 (ordinary character sequence)」となる。

       (NULL バイトも含む)  通常の文字列内の文字は、そのまま  format  から  s  にコピーされる。一
       方、変換指定の文字は以下のリストに示すように置換される。このリストでは、 tm 構造体のフィー
       ルドが参照される場合、その情報も記載している。

       %a     現在のロケールにおける曜日の省略名。 tm_wday から計算される。現在のロケールで使用さ
              れる具体的な名前は、引数に ABDAY_{17} を指定して nl_langinfo(3) を呼び出すことで取
              得できる。

       %A     現在のロケールにおける曜日の完全な名前。 tm_wday から計算される。現在のロケールで使
              用される具体的な名前は、引数に DAY_{17} を指定して nl_langinfo(3) を呼び出すことで
              取得できる。

       %b     現在のロケールにおける月の省略名。 tm_mon  から計算される。現在のロケールで使用され
              る具体的な名前は、引数に  ABMON_{112} を指定して nl_langinfo(3) を呼び出すことで取
              得できる。

       %B     現在のロケールにおける月の完全な名前。 tm_mon  から計算される。現在のロケールで使用
              される具体的な名前は、引数に  MON_{112} を指定して nl_langinfo(3) を呼び出すことで
              取得できる。

       %c     現在のロケールにおいて一般的な日付・時刻の表記。現在のロケールで使用される具体的な
              フォーマットは、  %c 変換指定の場合は D_T_FMT を、 %Ec 変換指定の場合は ERA_D_T_FMT
              を引数に指定して nl_langinfo(3) を呼び出すことで取得できる。 POSIX ロケールでは  %a
              %b %e %H:%M:%S %Y と等価である。

       %C     世紀に対応する  2 桁の整数 (year/1000)。 %EC 変換指定は、西暦以外の年数表記 ("era")
              の名前に対応する。 tm_year から計算される。 (SU)

       %d     月内通算日 (10 進数表記) (01-31)。 tm_mday から計算される。

       %D     %m/%d/%y と等価。(うえっ、アメリカ専用だ。アメリカ以外の国では %d/%m/%y  の方が一般
              的だ。紛らわしいので、使用すべきではない。) (SU)

       %e     %d  と同様に月内通算日を  10  進数で表現するが、 1 桁の場合 10 の位にゼロを置かずス
              ペースを置く。 tm_mday から計算される。 (SU)

       %E     別形式 (西暦以外の年数表記; "era") を使用する際の修飾子。下記参照。 (SU)

       %F     %Y-%m-%d と等価 (ISO 8601 形式の日付フォーマット)。 (C99)

       %G     ISO 8601 の週 (ISO 8601 week) に基づく年の表示。「注意」の節を参照)。世紀も 10 進数
              で表す。  ISO 週番号 (%V を参照) に対応した 4 桁の西暦年。 これは基本的には %Y と同
              じ形式だが、ISO        週数が前年や翌年になる場合にはその年が使用される点が異なる。
              tm_year, tm_yday, tm_wday から計算される。 (TZ)

       %g     %G   と同様。ただし、世紀を含まず下  2  桁のみを表示  (00–99)。  tm_year,  tm_yday,
              tm_wday から計算される。 (TZ)

       %h     %b と等価 (SU)

       %H     24 時間表記での時 (hour) (00-23)。 tm_hour から計算される。

       %I     12 時間表記での時 (hour) (01-12)。 tm_hour から計算される。

       %j     年の初めから通算の日数 (001-366)。 tm_yday から計算される。

       %k     24 時間表記での時 (0-23)。 1 桁の場合には前にゼロでなくスペースが置かれる。 %H も参
              照。 tm_hour から計算される。 (TZ)

       %l     12 時間表記での時 (0-12)。 1 桁の場合には前にゼロでなくスペースが置かれる。 %I も参
              照。 tm_hour から計算される。 (TZ)

       %m     10 進数表記の月 (01-12)。 tm_mon から計算される。

       %M     10 進数表記の分 (00-59)。 tm_min から計算される。

       %n     改行 (SU)

       %O     別の数値シンボルを使用する際の修飾子。下記参照。 (SU)

       %p     現在のロケールにおける「午前」「午後」に相当する文字列。 英語の場合には "AM" または
              "PM" となる。 正午は「午後」、真夜中は「午前」として扱われる。 tm_hour から計算され
              る。現在のロケールで "AM" と "PM" に対応する文字列表現は、それぞれ AM_STRPM_STR
              を指定して nl_langinfo(3) を呼び出すことで取得できる。

       %P     %p  と同様であるが小文字が使用される。 "am" や "pm"、もしくは現在のロケールでの対応
              する文字列となる。 tm_hour から計算される。 (GNU)

       %r     午前・午後形式での時刻。現在のロケールで使用される具体的なフォーマットは、引数に
              T_FMT_AMPM  を指定して nl_langinfo(3) を呼び出すことで取得できる。 POSIX ロケールで
              は %I:%M:%S %p と等価である。 (SU)

       %R     24 時間表記での時刻、秒は表示しない (%H:%M)。 秒を含んだものは以下の %T  を参照する
              こと。(SU)

       %s     紀元  (Epoch; 1970-01-01 00:00:00 +0000 (UTC)) からの秒数。 mktime(tm) から計算され
              る。 (TZ)

       %S     秒 (10 進数表記) (00-60)。時々ある閏秒に対応するため、値の範囲は 60  までとなってい
              る。 tm_sec から計算される。

       %t     タブ文字 (SU)

       %T     24 時間表記の時間 (%H:%M:%S) (SU)

       %u     週の何番目の日 (10 進数表記) か。月曜日を 1 とする (1-7)。 %w も参照。 tm_wday から
              計算される。 (SU)

       %U     年の初めからの通算の週番号 (10 進数表記) (00-53)。 その年の最初の日曜日を、第 1  週
              の始まりとして計算する。  %V%W も参照すること。 tm_ydaytm_wday から計算され
              る。

       %V     ISO 8601 形式での年の始めからの週番号 (「注意」の節を参照)。 10 進数表記で、01 から
              53 の値となる。週番号は、新しい年が少なくとも 4 日以上含まれる最初の週を 1 として計
              算する。 %U%W も参照のこと。 tm_year, tm_yday, tm_wday から計算される。 (SU)

       %w     週の何番目の日 (10 進数表記) か。日曜日を 0 とする。(0-6)。 %u も参照。 tm_wday  か
              ら計算される。

       %W     年の初めからの通算の週番号  (10 進数表記) (00-53)。 その年の最初の月曜日を、第 1 週
              の始まりとして計算する。 %V%W も参照すること。 tm_ydaytm_wday  から計算され
              る。

       %x     現在のロケールで一般的な日付表記。時刻は含まない。現在のロケールで使用される具体的
              なフォーマットは、 %x 変換指定の場合は D_FMT を、 %Ex 変換指定の場合は ERA_D_FMT を
              引数に指定して、 nl_langinfo(3) を呼び出すことで取得できる。 POSIX ロケールでは、こ
              れは %m/%d/%y と等価である。

       %X     現在のロケールで一般的な時刻表記。日付は含まない。現在のロケールで使用される具体的
              なフォーマットは、 %X 変換指定の場合は T_FMT を、 %EX 変換指定の場合は ERA_T_FMT を
              引数に指定して、 nl_langinfo(3) を呼び出すことで取得できる。 POSIX ロケールでは、こ
              れは %H:%M:%S と等価である。

       %y     西暦の下 2 桁 (世紀部分を含まない年) (00 から 99)。 %Ey 変換指定は。 %EC 変換指定で
              示される西暦以外の年数表記 ("era") における初めからの年数に対応する。 tm_year  から
              計算される。

       %Y     世紀部分を含めた 10 進表記の西暦年。 %EY 変換指定は別形式の年表記の完全な表現に対応
              する。 tm_year から計算される。

       %z     +hhmm-hhmm の形式のタイムゾーン (UTC へのオフセット時間)。(SU)

       %Z     タイムゾーン名または省略名。

       %+     date(1) 形式での日時。 glibc2 ではサポートされていない。 (TZ)

       %%     '%' 文字

       いくつかの変換指定では、変換指定文字の前に EO 「修飾子」を置くことによって別書式を使用
       するように指定することができる。 現在のロケールにおいて別書式が存在しない場合には、 通常の
       変換指定が使用されたかのように動作する (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 修飾子を
       使った場合のデータ表現に適用されるルールは、 nl_langinfo(3) の引数に ERA  を指定することで
       取得できる。このような別表現の例としては  ja_JP glibc ロケールでの日本の年号 (「昭和」「平
       成」など) によるカレンダー表記がある。

返り値

       終端のヌルバイトを含めた結果の文字列の長さが max バイトを超えなかった場合、 strftime()  関
       数は配列  s に格納されたバイト数を返す (このバイト数に終端のヌルバイトは含まれない)。 終端
       のヌルバイトを含めた結果の文字列の長さが max バイトを超える場合には、 strftime() は 0 を返
       し、配列の内容は不定となる。

       返り値  0 は必ずしもエラーを意味している訳ではないので注意すること。例えば、多くのロケール
       では %p は空文字列を返す。同様に、空の format 文字列は空文字列を返す。

環境変数

       環境変数 TZLC_TIME が使用される。 (訳注: LC_ALL が設定されている場合には LC_TIME  より
       もそちらが優先される。 LC_TIMELC_ALL も設定されていない場合には LANG が使用される。)

属性

       この節で使用されている用語の説明については、 attributes(7) を参照。

       ┌─────────────────┬───────────────┬────────────────────┐
       │インターフェース属性                 │
       ├─────────────────┼───────────────┼────────────────────┤
       │strftime()       │ Thread safety │ MT-Safe env locale │
       └─────────────────┴───────────────┴────────────────────┘

準拠

       SVr4,   C89,  C99.  個々の変換が厳密にどの規格に含まれるかをマークで示している。「マークな
       し」は ANSI C、「SU」は統一 UNIX 規格を、「TZ」は Olson の timezone  パッケージ、「GNU」は
       glibc   を示す。  glibc2  では  %+  はサポートされていないが、  いくつかの拡張が行われてい
       る。POSIX.1 では ANSI C のみを参照している。 POSIX.2 の date(1)   のところに記述されている
       幾つかの拡張は strftime() にも適用できるだろう。 %F 変換は C99 と POSIX.1-2001 にある。

       SUSv2  では、 %S は 00 から 61 の範囲をとると規定されている。 これは、1 分間のうち閏秒が 2
       つ入る可能性が理論的にはあることを考慮してのものである (実際には、このような状況はこれまで
       一度も 起こっていない)。

注意

   ISO 8601 の暦週日付
       %G,  %g, %V は、ISO 8601 標準により定義された週単位表記の年により 計算される値を出力する。
       ISO 8601 標準の週単位表記では、週は月曜日から開始され、 週番号は、年の最初の週が  01  とな
       り、最後の週は  52 か 53 となる。 週 01 は、新しい年が 4 日以上含まれる最初の週である。 言
       い換えると、週 01 は、その年の木曜日を含む最初の週、 つまり 1 月 4  日を含む週ということで
       ある。  新しい年のカレンダー上の最初の週に新しい年が 3 日以下しか含まれない場合、 ISO 8601
       の週単位表記では、これらの日を前の年の週 53 の一部とみなす。 例えば、2010 年 1 月 1 日は金
       曜日であり、 その週には 2010 年の日が 3 日しか含まれない。 したがって、ISO 8601 の週単位表
       記では、これらの日は 2009 年 (%G)  の週 53 (%V) の一部となる。 ISO 8601 の 2010 年の週  01
       は  2010  年 1 月 4 日の月曜日から始まる。同様に、 2011 年 1 月の最初の 2 日は 2010 年の週
       52 の一部とみなされる。

   glibc での注意
       glibc では変換指定にいくつか拡張を行っている (これらの拡張は POSIX.1-2001 には規定されてい
       ないが、  他のいくつかのシステムで同様の機能が提供されている)。 '%' 文字と変換指定文字の間
       に、オプションとして フラグ とフィールドの  を指定できる (これらを指定する場合には EO 修飾子の前に置く)。

       以下のフラグ文字が使用できる。

       _      (下線)  数値の結果文字列のパディング (穴埋め) をスペース (空白文字) で行う。

       -      (ダッシュ)  数値の結果文字列に対するパディングを行わない。

       0      変換指定文字がデフォルトではスペースでパディングを行う場合でも、 数値の結果文字列へ
              のパディングを 0 で行う。

       ^      結果文字列中のアルファベット文字を大文字に変換する。

       #      結果文字列の大文字・小文字を入れ替える  (このフラグは特定の変換指定文字でしか機能し
              ない。その中でも 本当に有用なのは %Z の場合だけである)。

       オプションの    10    進数の幅指定子はフラグの後ろに置くことができる   (フラグはなくてもよ
       い)。フィールドの本来の大きさが指定された幅よりも 小さい場合、結果文字列の左側は指定された
       幅までパディングされる。

バグ

       出力文字列が  max  バイトを超えてしまう場合、  errno は設定「されない」。 このため、このエ
       ラーと、 format 文字列がきちんと処理されて長さ 0  の出力文字列が生成される場合、を区別する
       ことができない。  POSIX.1-2001 では strftime() に関して errno に設定される値について一切規
       定して「いない」。

       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 オプションを 提供しており、上
       記の回避策はもはや必要ない。

       RFC 2822 準拠の日付形式 (%a と %b は英語ロケール)

            "%a, %d %b %Y %T %z"

       RFC 822 準拠の日付形式 (%a と %b は英語ロケール)

            "%a, %d %b %y %T %z"

   サンプルプログラム
       以下のプログラムを使うと 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 <time.h>
       #include <stdio.h>
       #include <stdlib.h>

       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);
       }

関連項目

        date(1), time(2), ctime(3), nl_langinfo(3), setlocale(3), sprintf(3), strptime(3)

この文書について

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