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

標準

標準/拡張機能 C/C++ 依存項目

ISO C
POSIX.1
XPG4
XPG4.2
C99
Single UNIX Specification、バージョン 3

 両方  

形式

#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_year、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 月 4 日と 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 時間帯の名前と置換する、または時間帯が利用できない場合 は、文字なし。
%% % と置換。

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

コピー中のオブジェクトがオーバーラップする場合、その動作は未定義です。maxsize によって、配列にコピーできる 文字の最大数が指定できます。

strftime() が POSIX 以外のアプリケーションにより呼び出されると、これにより、LC_TOD ロケール・カテゴリーから適切な時間帯名情報が 取得されます。時間帯名情報が現行 LC_TOD ロケール・カテゴリーで未指定の場合には、標準時間名であれば STD、夏時間名であれば DST、協定世界時 (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 を戻し、ストリングの内容は不確定となります。

例

CELEBS42 
⁄* 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

関連情報

親トピック: ライブラリー関数