名称

wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf — フォーマットした (書式) ワイド文字出力変換

ライブラリ

Standard C Library (libc, -lc)

書式

#include < stdio.h>
#include < wchar.h>

int
fwprintf( FILE * restrict stream, const wchar_t * restrict format, ...);

int
swprintf( wchar_t * restrict ws, size_t n, const wchar_t * restrict format, ...);

int
wprintf( const wchar_t * restrict format, ...);

#include < stdarg.h>

int
vfwprintf( FILE * restrict stream, const wchar_t * restrict, va_list ap);

int
vswprintf( wchar_t * restrict ws, size_t n, const wchar_t *restrict format, va_list ap);

int
vwprintf( const wchar_t * restrict format, va_list ap);

解説

wprintf() 関数ファミリは、下記に説明するように format に従って出力を行います。 wprintf() と vwprintf() 関数は、標準出力ストリーム stdout に出力を書き込みます。 fwprintf() と vfwprintf() は、与えられた出力ストリーム stream に出力を書き込みます。 swprintf() とd vswprintf() は、ワイド文字列 ws に出力を書き込みます。

これらの関数は、後に続く引数 (または stdarg(3) の可変長引数機能でアクセスできる引数) が出力のためにどのように変換するかを指定する、 format 文字列の制御に従って出力を書き込みます。

これらの関数は印刷された文字の数 (文字列への出力を終了するために使用される、最後の‘ \0’は含みません) を返します。

swprintf() と vswprintf() 関数は n 以上のワイド文字が書き込まれるように要求されたなら、失敗します。

フォーマット (書式) 文字列は、0 以上の指令から構成されています: この指令は、出力ストリームに変更されずにコピーされる通常文字 ( % 以外)、および 0 以上の後続の引数を取って来るそれぞれの変換指定です。それぞれの変換指定は、 % 文字で始まります。引数は、(型促進の後に) 変換指示子で適切に対応しなければなりません。 % の後には、次の順番で現れます。

• $ が続く 10 進数文字列から成り、次にアクセスする引数を指定するオプションフィールド。このフィールドが提供されないなら、最後にアクセスされた引数に続く引数が使用されます。引数は 1 から始まる番号が付けられます。書式文字列中でアクセスされない引数がアクセスされる引数に組み入れられている場合、結果は不定になります。
• 0 以上の次のフラグ:

  ‘ #’

  値は“代替形式”に変換されるべきです。 c, d, i, n, p, s および u 変換について、このオプションは効果がありません。 o 変換について、数値の精度は出力文字列の最初の文字を 0 に (0 値が 0 の明示的な精度で印刷される場合を除いて) 強制するために増加させられます。 x と X 変換について、0 以外の結果の前に文字列‘ 0x’ (または X 変換のためは‘ 0X’) が付きます。 a, A, e, E, f, F, g および G 変換について、数字がそれに続かなくても、結果は常に小数点が含まれます (通常は、数字が続く場合のみ、それらの変換の結果に小数点が現れます)。 g および G 変換について、後続する 0 はそうでなければ (0 が後続するように) 結果から取り除かれません。

  ‘ 0’ (zero)

  0 パディング。 n 変換を除くすべての変換について、変換された値は空白ではなく 0 で左に詰められます。精度が数値変換 ( d, i, o, u, i, x および X) で与えられる場合、 0 フラグは無視されます。

  ‘ -’

  負のフィールド幅のフラグ。変換された値はフィールド境界で左に揃えられます。 n 変換を除いて、変換された値は空白か 0 の左でなく、右に空白が埋められます。 - と 0 を両方が与えられる場合は 0 を無効にします。

  ‘ ’ (space)

  空白は符号付き変換 ( a, A, d, e, E, f, F, g, G または i) によって生成される正の数値の前に残されるべきです。

  ‘ +’

  符号は、符号付き変換によって生成される数値の前に常に置かれなければなりません。 + と空白が両方とも使用される場合は空白を無効にします。

  ‘ '’

  10 進変換 ( d, u または i) か浮動小数点変換 ( f または F) の整数部 (指数部) は、 localeconv(3) によって返された非通貨のセパレータ (分離記号) を使用することで千単位でグループ化され、分離されるべきです。

• 最低フィールド幅を指定するオプションの 10 進数文字列。変換された値がフィールドの幅より少ない文字数の場合は、フィールドの幅を調整するために左に (左揃えフラグが指定された場合は右に) 空白が埋められます。
• オプションの数字文字列が続くピリオド . の形式のオプションの精度。数字文字列を省略した場合、精度は 0 になります。 d, i, o, u, x および X 変換のために現れる最低の桁の数、 a, A, e, E, f, および F 変換のために小数点の後に現れるための桁の数、 g および G 変換のために有効な桁の最大数、 s 変換のための文字列から印刷される最大の文字の数が与えられます。
• 引数のサイズを指定する、オプションの長さ修飾子です。 The following length modifiers are valid for the 次の長さ修飾子は d, i, n, o, u, x または X 変換で有効です:

  修飾子	d, i	o, u, x, X	n
  hh	signed char	unsigned char	signed char *
  h	short	unsigned short	short *
  l (エル)	long	unsigned long	long *
  ll (エルエル)	long long	unsigned long long	long long *
  j	intmax_t	uintmax_t	intmax_t *
  t	ptrdiff_t	(注参照)	ptrdiff_t *
  z	(注参照)	size_t	(注参照)
  q (非推奨)	quad_t	u_quad_t	quad_t *

  注: t 修飾子は、 o, u, x または X 変換に適用されるとき、引数がサイズで unsigned タイプと ptrdiff_t が同等であることを示します。 z 修飾子は、 d または i 変換に適用されるとき、引数がサイズで signed タイプと size_t が同等であることを示します。同様に、 n 変換に適用されるとき、それは、引数がサイズで signed タイプへのポインタと size_t が同等であることを示します。

  次の長さ修飾子 a, A, e, E, f, F, g または G 変換で有効です:

  修飾子	a, A, e, E, f, F, g, G
  L	long double

  次の長さ修飾子 c または s 変換で有効です:

  修飾子	c	s
  l (エル)	wint_t	wchar_t *

• 適用される変換の型を指定する文字。

フィールド幅か精度、またはその両方は、アスタリスク‘ *’、または数字文字列の代わりに 1 つ以上の 10 進数と‘ $’が続くアスタリスクで指示できます。この場合、 int 引数はフィールド幅か精度を供給します。負のフィールド幅は、正のフィールド幅が続く左揃えフラグとして扱われます。負の精度は、まるで欠落しているかのように扱われます。 1 つのフォーマット (書式) 指令が位置引数 ( nn$) と位置以外の引数が混在している場合、結果は未定義になります。

変換指示子とその意味は次の通りです:

diouxX

int (または適切な可変) 引数が、符号付き 10 進 ( d と i)、符号なし 8 進 ( o)、符号なし 10 進 ( u)、符号なし 16 進 ( x と X) 記法に変換されます。文字“ abcdef”は x 変換のために使われます。文字“ ABCDEF”は X 変換のために使われます。精度は、もしあれば、現れるべき桁の最低数を与えます。変換された値が少ない桁を要求する場合は、左に 0 が埋められます。

DOU

long int 引数は、それぞれの形式が ld, lo および lu であるかのように符号付き 10 進、符号なし 8 進、符号なし 10 進に変換されます。これらの変換文字は非推奨であり、最終的には消滅するでしょう。

eE

double 引数が丸められ、[ -] d . ddd e± dd のスタイルに変換されます。ここで、小数点文字の前は 1 桁で、後の桁の数は精度と等しくなります。精度が欠けている場合は 6 が取られます。精度が 0 である場合、小数点文字は現れません。 E 変換では、指数を導入するために、文字 (‘ e’ではなく) ‘ E’が使われます。指数は、少なくとも 2 桁が常に含まれます。値が 0 である場合、指数は 00 になります。

a, A, e, E, f, F, g および G 変換において、正と負の無限は小文字の変換文字を使用するとき、それぞれ inf と -inf で表現され、大文字の変換文字を使用するとき、それぞれ INF と -INF で表現されます。同様に、NaN は小文字の変換を使用するとき、 nan で、大文字の変換を使用するとき、 NAN で表現されます。

fF

double 引数が丸められ、[ -] ddd . ddd のスタイルで 10 進記法に変換されます。ここで、小数点文字の後の桁の数は、精度指定に等しくなります。精度が欠けている場合は 6 が取られます。精度が明白に 0 である場合、小数点文字は現れません。小数点が現れる場合は、それの前に少なくとも 1 桁が現れます。

gG

double 引数は、スタイル f か e (あるいは G 変換のためには F または E) で変換されます。精度は有効桁数を指定します。精度が欠けている場合は 6 桁が与えられます。精度が 0 である場合は 1 として扱われます。変換後の指数が-4 より小さいか精度以上である場合は、スタイル e が使用されます。後続する 0 は、結果の小数部から取り除かれます。小数点は、少なくとも 1 つ桁が続く場合のみ現れます。

aA

double 引数はスタイル[ -] 0x h . hhhp[ ±] d で 16 進記法へ変換されます。ここで、16 進ポイント文字の後の桁数は精度指定と同じです。精度が欠けている場合、浮動小数点の数を正確に表現するために十分なようにそれを受け取ります。精度が明らかに 0 であるなら、16 進ポイント文字は現れません。これは仮数+指数の内部の浮動小数点表現の正確な変換です。[ -] 0x h . hhh 部分は正確に仮数を表現します。非正規化にされた仮数だけには、16 進ポイントの左への 0 値があります。 p はリテラル文字‘ p’で、指数は正または負のサインで先行され、指数を表現するために十分な文字だけを使用して、10 進数で表現されます。 A 変換は、16 進数桁を表すために接頭辞 (“ 0x”よりむしろ) “ 0X”、文字 (“ abcdef”よりむしろ) “ ABCDEF”および仮数と指数を分離するために (‘ p’よりむしろ) 文字‘ P’を使用します。

C

l (エル) 修飾子がある c として取り扱われます。

c

int 引数は unsigned char に変換され、そして btowc(3) によって wchar_t に変換され、結果の文字が書き込まれます。

l (エル) 修飾子が使用されているなら、 wint_t 引数は wchar_t に変換され、書き込まれます。

S

l (エル) 修飾子がある s として取り扱われます。

s

char * 引数が、マルチバイトシーケンスを含む文字型の配列を指すポインタ (文字列へのポインタ) が期待されます。配列の文字は、ワイド文字に変換され、終端の ヌル文字 まで (しかし含まずに) 書き込まれます。精度が指定されている場合、指定された数以上は書き込まれません。精度が与えられる場合、ヌル文字は存在する必要はありません。精度が指定されていない場合、または精度が配列のサイズより大きい場合、配列は終端の ヌル文字 を含まなければなりません。

l (エル) 修飾子が使用されているなら、 wchar_t * 引数はワイド文字 (ワイド文字列へのポインタ) の配列へのポインタであると期待されます。文字列中のそれぞれのワイド文字が書き込まれます。配列からのワイド文字は終端のワイド ヌル 文字 (しかし、含めない) まで書き込まれます。精度が指定されるなら、わずかの指定された数が (シフトシーケンスを含んで) 書き込まれます。精度が与えられるなら、ヌル文字は存在する必要はありません。精度が指定されないか、または文字列のマルチバイト表現を示す必要があるバイト数より大きいなら、配列は終端のワイド ヌル 文字を含まなければなりません。

p

void * ポインタ引数は、16 進で (あたかも‘ %#x’か‘ %#lx’によるかのように) 印刷されます。

n

これまでに書き込まれた文字数は、 int * (または可変) ポインタ引数で示された整数に格納されます。引数は変換されません。

%

‘ %’が書き込まれます。引数は変換されません。完全な変換指示は‘ %%’です。

小数点文字はプログラムのロケール (カテゴリ LC_NUMERIC) で定義されます。

フィールド幅が存在しないか小さい場合でも、決して数値フィールドは切り捨てられません。変換の結果がフィールド幅より大きい場合、フィールドは変換結果を含むために拡張されます。

関連項目

btowc(3), fputws(3), printf(3), putwc(3), setlocale(3), wcsrtombs(3), wscanf(3)

規格

printf(3) の バグ セクションで注意された警告に従って、 wprintf(), fwprintf(), swprintf(), vwprintf(), vfwprintf() と vswprintf() 関数は、 ISO/IEC 9899:1999 (“ISO C99”) に適合しています。

セキュリティの考察

printf(3) を参照してください。