strftime

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

名前

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

ライブラリ

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

書式

#include <time.h>

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

size_t strftime_l(size_t max;
                char s[restrict max], size_t max,
                const char *restrict format,
                const struct tm *restrict tm,
                locale_t locale);

説明

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_{1-7} を指定して nl_langinfo(3) を呼び出すことで取得できます。
%A: 現在のロケールにおける曜日の完全な名前(tm_wday から計算されます)。現在のロケールで使用される具体的な名前は、引数に DAY_{1-7} を指定して nl_langinfo(3) を呼び出すことで取得できます。
%b: 現在のロケールにおける月の省略名(tm_mon から計算されます)。現在のロケールで使用される具体的な名前は、引数に ABMON_{1-12} を指定して nl_langinfo(3) を呼び出すことで取得できます。
%B: 現在のロケールにおける月の完全な名前(tm_mon から計算されます)。現在のロケールで使用される具体的な名前は、引数に MON_{1-12} を指定して 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/100)。 (SU) (%EC変換指定は、年の名前に対応します。)(tm_yearから計算されます。)
%d: 月内通算日 (10 進数表記) (01-31)。 tm_mday から計算される。
%D: %m/%d/%y と等価。(うえっ、アメリカ専用だ。アメリカ以外の国では %d/%m/%y の方が一般的だ。国際的に使うところでは、紛らわしいので、使用すべきではない。) (SU)
%e: %d と同様に月内通算日を 10 進数で表現しますが、1 桁の場合 10 の位にゼロを置かずスペースを置きます。(SU) (tm_mday から計算されます。)
%E: 修飾子: 別形式 ("時代に基づく") を使用: 下記参照。 (SU)
%F: %Y-%m-%d と等価 (ISO 8601 形式の日付フォーマット)。 (C99)
%G: 西暦を 10 進数で表す ISO 8601 の週 (ISO 8601 week) に基づく年の表示。(「注意」の節を参照)。ISO 週番号 (%V を参照) に対応した 4 桁の西暦年。これは基本的には %Y と同じ形式ですが、ISO 週数が前年や翌年になる場合にはその年が使用される点が異なります。(TZ) (tm_year, tm_yday, tm_wday から計算されます。)
%g: %G と同様ですが、世紀を含まず下 2 桁のみを表示します (00-99)。(TZ) (tm_year, tm_yday, tm_wday から計算されます。)
%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 時間表記での時 (1-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_STR と PM_STR を指定して nl_langinfo(3) を呼び出すことで取得できます。)
%P: %p と同様ですが小文字が使用されます。 "am" や "pm"、もしくは現在のロケールでの対応する文字列となります。 tm_hour から計算されます。 (GNU)
%r: 午前・午後形式での時刻。 (SU) (現在のロケールで使用される具体的なフォーマットは、引数に T_FMT_AMPM を指定して nl_langinfo(3) を呼び出すことで取得できます。)(POSIX ロケールでは %I:%M:%S %p と等価です。
%R: 24 時間表記での時刻、秒は表示しません (%H:%M)。 (SU) 秒を含んだものは以下の %T を参照してください。
%s: 紀元 (Epoch; 1970-01-01 00:00:00 +0000 (UTC)) からの秒数。(TZ) (mktime(tm) から計算されます。)
%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_yday と tm_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_yday と tm_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) 形式での日時。(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 修飾子を使った場合のデータ表現に適用されるルールは、 nl_langinfo(3) の引数に ERA を指定することで取得できる。このような別表現の例としては ja_JP glibc ロケールでの日本の元号 (訳注:「令和」「平成」など) によるカレンダー表記があります。

strftime_l() は strftime() と同じですが、現在のロケールではなく指定された locale を使用する点が異なります。locale が無効な場合や LC_GLOBAL_LOCALE の場合の動作は未定義です。

返り値

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

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

環境変数

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

属性

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

インターフェース	属性	値
strftime(), strftime_l()	Thread safety	MT-Safe env locale

標準

strftime(): C11, POSIX.1-2008.
strftime_l(): POSIX.1-2008.

履歴

strftime(): SVr4, C89.
strftime_l(): POSIX.1-2008.

ANSI Cの変換(印なし)、統一UNIX企画の変換(SU マーク)、Olson の timezoneパッケージの変換(TZ マーク)、glibc の変換(GNU マーク)の間には、厳密な包含関係があります。ただし、glibc2 では %+ はサポートされていません。一方、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 標準により定義された週ベースの年から計算される値を出力します。この仕組みでは、週は月曜日から開始され、週番号は、年の最初の週が 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 には規定されていませんが、他のいくつかのシステムでは同様の機能が提供されています)。'%' 文字と変換指定文字の間に、オプションとして フラグ とフィールドの幅を指定できます (これらを指定する場合には E や O 修飾子の前に置きます)。

以下のフラグ文字が使用できます:

_: (下線) 数値の結果文字列のパディング (穴埋め) をスペース (空白文字) で行います。
-: (ダッシュ) 数値の結果文字列に対するパディングを行ないません。
0: 変換指定文字がデフォルトではスペースでパディングを行う場合でも、数値の結果文字列へのパディングを 0 で行ないます。
ha: 結果文字列中のアルファベット文字を大文字に変換します。
#: 結果文字列の大文字・小文字を入れ替えます (このフラグは特定の変換指定文字でしか機能しません。その中でも本当に有用なのは %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 <stdio.h> #include <stdlib.h> #include <time.h> int main(int argc, char *argv[]) {
    char outstr[200];
    time_t t;
    struct tm *tmp;
    if (argc != 2) {
        fprintf(stderr, "Usage: %s: <format-string>\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    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); }