strftime() - フォーマット設定された時刻への変換

規格

標準/拡張機能 C/C++ 依存項目
ISO C
POSIX.1
XPG4
XPG4.2

C99
Single UNIX Specification、バージョン 3
 both  

Format

#include <time.h>

size_t strftime(char * __restrict__ dest, size_t maxsize,
                const char * __restrict__ format, const struct tm * __restrict__ timeptr);

機能説明

format で示されるストリングに応じて、dest で 示される配列に、文字を入れます。 書式制御ストリングは、以下を含むマルチバイト文字 ストリングです。
  • 変換指定文字
  • 未変更の配列中にコピーされる通常のマルチバイト文字

変換される文字は、現行ロケールの LC_CTYPE カテゴリー および timeptr で示される時間構造体の値によって、判別されます。 timeptr が示す時間構造体は、通常は gmtime() または localtime() 関数の呼び出しにより取得されます。

表 1. strftime() により使用される変換指定子
指定子 意味
%a ロケールの省略曜日名と置換。
%A ロケールの正式曜日名と置換。
%b ロケールの省略月名と置換。
%B ロケールの正式月名と置換。
%c ロケールの日時と置換。
%C ロケールの世紀数 (100 で除算し、切り捨てた年) と置換。
%d 1 カ月の日 (01 ～ 31) と置換。
%D ロケールに関係なく、日付を mm/dd/yy 形式で挿入。
%e 1 カ月の日を 10 進数で挿入 (01 ～ 31)。 C POSIX でのみ、これは 2 文字、右寄せのブランク・フィールド です。
%E[cCxyY] 代替日時形式が利用できない場合は、%E 記述子が拡張されていないもう一方にマップされます。 例えば、%EC は %C にマップされます。
%Ec ロケールの代替日時表示と置換。
%EC ロケールの代替表示の基本年 (期間) 名と置換。
%Ex ロケールの代替日付表示と置換。
%EX ロケールの代替時間表示と置換。
%Ey ロケールの代替表示の %EC (年のみ) からのオフセットと 置換。
%EY 正式代替年表示と置換。
%F ISO 8601:2000 標準日付形式 ( %Y-%m-%dに相当 ) で置き換えます。 値は、 struct tm メンバー、tm_年次、 tm_mon、および tm_mday から取得されます。
%g 10 進数で表される、週に基づいた年号の末尾 2 桁 (00 から 99) と置換。
%G 4 桁の 10 進数で表される、週に基づいた年号と置換。
%h ロケールの省略月名と置換。 これは %b と同じです。
%H 10 進数 (00 ～ 23) で時間 (24 時間時計) と置換。
%I 10 進数 (01 ～ 12) で時間 (12 時間時計) と置換。
%j 1 年の日 (001 ～ 366) と置換。
%m 月 (01 ～ 12) と置換。
%M 分 (00 ～ 59) と置換。
%n 改行と置換。
%O[deHImMSUwWy] 代替日時形式が利用できない場合は、%E 記述子が拡張されていないもう一方にマップされます。 例えば、%Od は %d にマップされます。
%Od ロケールの代替数字シンボルを使用し、必要に応じ、ゼロの代替シンボル がある場合には先行ゼロ、そうでない場合には、先行スペースで 充てんした 1 カ月の日と置換。
%Oe ロケールの代替シンボルを使用して、月の日付 (必要な場合には、先行スペースで充てんされる) と置換。
%OH ロケールの代替シンボルを使用して、時間 (24 時間時計) と置換。
%OI ロケールの代替シンボルを使用して、時間 (12 時間時計) と置換。
%Om ロケールの代替数字シンボルを使用し、月と置換。
%OM ロケールの代替数字シンボルを使用し、分と置換。
%OS ロケールの代替数字シンボルを使用し、秒と置換。
%Ou ロケールの代替表示の数を使用して、曜日と置換 (月曜=1)。
%OU ロケールの代替数字シンボルを使用して、年の週番号 (日曜を週の初日とする、%U に対応する規則) と置換。
%OV ロケールの代替数字シンボルを使用して、年の週番号 (月曜を週の初日とする、%V に対応する規則) と置換。
%Ow ロケールの代替数字シンボルを使用し、曜日 (日曜 =0) と置換。
%OW ロケールの代替数字シンボルを使用して、1 年の週数と置換 (月曜 を週の初日とする)。
%Oy ロケールの代替表示で、ロケールの代替数字シンボルを使用して、年と置換 (%C からのオフセット)。
%p AM または PM のロケールの同値と置換。
%r %I:%M:%S %p と等しいストリングと置換。またはあれば、LC_TIME からの t_fmt_ampm を使用。
%R 24 時間表記 (%H:%M) の時間と置換。
%S 10 進数の秒数 (00 から 60) と置換。
%t タブと置換。
%T %H:%M:%S と等しいストリングと置換。
%u 月曜を 1 で表示し、曜日を 10 進数 (1 ～ 7) と置換。
%U 日曜を週の初日とした 1 年の週数 (00 ～ 53) と置換。 1 月の最初の日曜日が第 1 週の初日です。これより前の新年の日は第 0 週となります。
%V 月曜を週の初日とした 1 年の週数 (01 ～ 53) と置換。 1 月 1 日を含む週が新規年に 4 日以上ある場合、それは週 1 と見なされます。 それ以外の場合、これは前年の最後の週であり、翌週は週 1になります。 1 月の 1 月 4 日と 1 月の第 1 木曜日は、常に 1 週間です。
%w 日曜が 0 の曜日 (0 ～ 6) と置換。
%W 月曜を週の初日とした 1 年の週数 (00 ～ 53) と置換。
%x ロケールの日付表示と置換。
%X ロケールの時間表示と置換。
%y 世紀でない年 (00 ～ 99) と置換。
%Y 世紀の年と置換。
%z ISO8601:2000 標準形式の UTC からのオフセット (+hhmm または -hhmm) と置換。 例えば、「-0430」は UTC より 4 時間 30 分の遅れを意味しています (グリニッジの西側)。 tm_isdst がゼロの場合は、標準時刻オフセットが使用されます。 tm_isdst がゼロより大きい場合は、夏時間調整オフセットが使用されます。 tm_isdst が負の場合、または時間帯を判別できない場合は、文字は戻されません。
%Z 時間帯の名前と置換する、または時間帯が利用できない場合 は、文字なし。
%% % と置換。

データの形式はディレクティブだが、上記のいずれでもない場合には、% に続く文字が出力にコピーされます。

この動作は、コピーされるオブジェクトが重複している場合には 最大サイズ は、配列にコピーできる文字の最大数を指定します。

strftime() が POSIX 以外のアプリケーションにより呼び出されると、これにより、LC_TOD ロケール・カテゴリーから適切な時間帯名情報が 取得されます。 現行の LC_TOD ロケール・カテゴリーで時間帯名情報が指定されていない場合、タイム・ゾーン名は標準時名の場合は STD 、夏時間名の場合は DST 、 協定世界時 (UTC) (Coordinated Universal Time (UTC))の場合は UTC で、必要に応じてデフォルトになります。

注: %Z 変換指定子を変換するために、strftime() 関数には 時間帯名情報が必要です。 これは次のように取得されます。
  • strftime() 関数は、tzset() 関数を呼び出して、TZ (POSIX) または _TZ (non_POSIX) 環境変数を構文解析することによって、または現行の LC_TOD ロケール・カテゴリーから、時間帯情報を取得します。 strftime() への tm 構造体入力が、localtime() 呼び出し によって作成された場合には、strftime() により %Z が、TZ 環境変数または LC_TOD カテゴリー (TZ を検出または解析できない場合) で指定された標準または夏時間名文字に変換されます。
  • TZ も _TZ も定義されない場合、時間帯情報について現行ロケールの値が照会されます。 TZ も _TZ も定義されず、LC_TOD 時間帯情報が現行ロケールに存在しない場合、デフォルト値が現地時間に適用されます。 POSIX プログラムでは単にデフォルトで協定世界時 (UTC) になりますが、非 POSIX プログラムでは、システム・クロックの設定に基づいて UTC からのオフセットを確立します。 タイム・ゾーンをカスタマイズして現地時間で作業する方法について詳しくは、 z/OS XL C/C++ プログラミング・ガイド」の「タイム・ゾーンのカスタマイズ」を参照してください。

strftime() への時間構造体入力の tm_isdst フラグ により、%Z を標準または夏時間名文字で置き換えるかどうかが 決定されます。 標準または夏時間名文字が現行 LC_TOD ロケール・カテゴリー で、または解析 TZ から使用不可の場合には、strftime() により 標準の場合には STD、夏時間名の場合には文字 DST が使用されます。

strftime() への tm 構造体入力が gmtime() 関数に よって作成された場合には、strftime() は、%Z を現行 LC_TOD ロケール・カテゴリーで 指定された UCTNAME 文字で、または UCTNAME が指定 されない場合には、UTC で置き換えます。

戻り値

正常に実行された場合、strftime() は、配列中に入れられた文字数 (バイト数) を、終了 NULL 文字を含まずに、戻します。

正常に実行されなかった場合、strftime() は、0 を戻し、ストリングの内容は不確定となります。

例

ケレブス42 
/* CELEBS42                                      

   This example places characters into the array dest and prints                
   the resulting string.                                                        
                                                                                
 */                                                                             
#include <stdio.h>                                                              
#include <time.h>                                                               
                                                                                
int main(void)                                                                  
{                                                                               
  char dest[70];                                                                
  int ch;                                                                       
  time_t temp;                                                                  
  struct tm *timeptr;                                                           
                                                                                
  temp = time(NULL);                                                            
  timeptr = localtime(&temp);                                                   
  ch = strftime(dest,sizeof(dest)-1,"Today is %A,"                              
              " %b %d. \n Time: %I:%M %p", timeptr);                            
  printf("%d characters placed in string to make: \n \n %s", ch, dest);         
}
出力
44 characters placed in string to make:

 Today is Friday, Jun 16.
 Time: 03:07 PM

関連情報