Man page - vsprintf(3)

Packages contains this manual

Available languages:

en fr nl ja de

Manual

PRINTF

名 前
書 式
説 明
フ ォ ー マ ッ ト 文 字 列 の フ ォ ー マ ッ ト
フ ラ グ 文 字
フ ィ ー ル ド 幅
精 度
長 さ 修 飾 子
変 換 指 定 子
返 り 値
属 性
準 拠
注 意
バ グ
例
関 連 項 目
こ の 文 書 に つ い て

名 前

printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf, vsnprintf - 指 定 さ れ た 書 式 に 変 換 し て 出 力 を 行 う

書 式

#include <stdio.h>

int printf(const char * format , ...);
int fprintf(FILE * stream , const char * format , ...);
int dprintf(int fd , const char * format , ...);
int sprintf(char * str , const char * format , ...);
int snprintf(char * str , size_t size , const char * format , ...);

#include <stdarg.h>

int vprintf(const char * format , va_list ap );
int vfprintf(FILE * stream , const char * format , va_list ap );
int vdprintf(int fd , const char * format , va_list ap );
int vsprintf(char * str , const char * format , va_list ap );
int vsnprintf(char * str , size_t size , const char * format , va_list ap );

glibc 向 け の 機 能 検 査 マ ク ロ の 要 件 ( feature_test_macros (7) 参 照 ):

snprintf (), vsnprintf ():

_XOPEN_SOURCE >= 500 || _ISOC99_SOURCE ||
|| /* Glibc versions <= 2.19: */ _BSD_SOURCE

dprintf (), vdprintf ():

glibc 2.10 以 降 :

_POSIX_C_SOURCE >= 200809L

glibc 2.10 よ り 前 :

_GNU_SOURCE

説 明

printf () 関 数 グ ル ー プ は 、 以 下 で 述 べ る よ う に 、 format に 従 っ て 出 力 を 生 成 す る も の で あ る 。 printf () と vprintf () は 出 力 を stdout (標 準 出 力 ス ト リ ー ム ) に 書 き 出 す 。 fprintf () と vfprintf () は 出 力 を 指 定 さ れ た 出 力 stream に 書 き 出 す 。 sprintf (), snprintf (), vsprintf (), vsnprintf () は 出 力 を 文 字 列 str に 書 き 込 む 。

dprintf () 関 数 は fprintf (3) 関 数 と 同 じ だ が 、 こ の 関 数 は stdio ス ト リ ー ム で は な く フ ァ イ ル デ ィ ス ク リ プ タ ー fd に 対 し て 出 力 を 行 う 点 が 異 な る 。

snprintf () と vsnprintf () は 最 大 で size バ イ ト を str に 書 き 込 む ( size に は 文 字 列 を 終 端 す る ヌ ル バ イ ト ('\0') も を 含 ま れ る )。

vprintf (), vfprintf (), vdprintf (), vsprintf (), vsnprintf () の 各 関 数 は そ れ ぞ れ printf (), fprintf (), dprintf (), sprintf (), snprintf (), の 各 関 数 と 等 価 で あ り 、 可 変 数 引 数 の 代 わ り に va_list を 引 数 と し て 呼 び 出 さ れ る 点 だ け が 異 な る 。 こ れ ら の 関 数 で は va_end マ ク ロ は 呼 び 出 さ れ な い 。 こ れ ら の 関 数 は va_arg を 呼 び 出 す の で 、 呼 び 出 し 後 の ap の 値 は 未 定 義 で あ る 。 stdarg (3) を 参 照 の こ と 。

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

C99 と POSIX.1-2001 で は 、 sprintf (), snprintf (), vsprintf (), vsnprintf () の 呼 び 出 し で 、 範 囲 が 重 複 す る オ ブ ジ ェ ク ト 間 で コ ピ ー が 発 生 す る 場 合 の 結 果 は 不 定 で あ る と 規 定 さ れ て い る (例 え ば 、 出 力 先 の 文 字 列 と 入 力 さ れ た 引 数 の 一 つ が 同 じ バ ッ フ ァ ー を 参 照 し て い る 場 合 な ど で あ る )。 「 注 意 」 の 節 を 参 照 。

フ ォ ー マ ッ ト 文 字 列 の フ ォ ー マ ッ ト

フ ォ ー マ ッ ト 文 字 列 は 文 字 の 列 で 、 (も し あ る な ら ) 初 期 シ フ ト 状 態 で 始 ま り 、 初 期 シ フ ト 状 態 で 終 わ る 。 フ ォ ー マ ッ ト 用 の 文 字 列 は 0 個 以 上 の 命 令 (directives) に よ っ て 構 成 さ れ る 。 命 令 に は 、 通 常 文 字 と 変 換 指 定 (conversion specifications) が あ る 。 通 常 文 字 は % 以 外 の 文 字 で 、 出 力 ス ト リ ー ム に そ の ま ま コ ピ ー さ れ る 。 変 換 指 定 は 、 そ れ ぞ れ が 0 個 以 上 の 引 数 を 取 る 。 各 変 換 指 定 は 文 字 % で 始 ま り 、 変 換 指 定 子 (conversion specifier) で 終 わ る 。 % と 変 換 指 定 子 の 間 に は 、 0 個 以 上 の フ ラ グ 、 最 小 フ ィ ー ル ド 幅 、 精 度 、 長 さ 修 飾 子 を (こ の 順 序 で ) 置 く こ と が で き る 。

The arguments must correspond properly (after type promotion) with the conversion specifier. By default, the arguments are used in the order given, where each '*' (see Field width and Precision below) and each conversion specifier asks for the next argument (and it is an error if insufficiently many arguments are given). One can also specify explicitly which argument is taken, at each place where an argument is required, by writing "%m$" instead of '%' and "*m$" instead of '*', where the decimal integer m denotes the position in the argument list of the desired argument, indexed starting from 1. Thus,

printf("%*d", width, num);

と

printf("%2$*1$d", width, num);

は 等 価 で あ る 。 二 番 目 の 書 き 方 で は 同 じ 引 数 を 繰 り 返 し 参 照 す る こ と が で き る 。 C99 標 準 に は 、 Single UNIX Specification 由 来 の '$' を 使 っ た 書 き 方 は 含 ま れ て い な い 。 '$' を 使 っ た ス タ イ ル を 使 う と 、 引 数 を 取 る 変 換 及 び 幅 と 精 度 の 引 数 を 全 て こ の ス タ イ ル で 指 定 し な け れ ば な ら な い が 、 引 数 を 消 費 し な い "%%" フ ォ ー マ ッ ト と 混 ざ っ て い る か も し れ な い 。 '$' で 指 定 さ れ る 引 数 の 番 号 に 空 き が あ っ て は な ら な い 。 例 え ば 、 も し 引 数 1 と 3 が 指 定 さ れ る と 、 引 数 2 も フ ォ ー マ ッ ト 文 字 列 の ど こ か で 指 定 さ れ な け れ ば な ら な い 。

数 値 変 換 に は 小 数 点 や 1000 単 位 の 区 切 り 文 字 を 使 う も の も あ る 。 実 際 に ど の 文 字 を 使 う か は ロ ケ ー ル の LC_NUMERIC に よ る ( setlocale (3) 参 照 )。 POSIX ロ ケ ー ル で は 小 数 点 に '.' を 用 い 、 区 切 り 文 字 は 使 わ な い 。 従 っ て 、

printf("%'.2f", 1234567.89);

は 、 POSIX ロ ケ ー ル で は "1234567.89" 、 nl_NL ロ ケ ー ル で は "1234567,89"、 da_DK ロ ケ ー ル で は "1.234.567,89" と な る 。

フ ラ グ 文 字

% 文 字 の 後 ろ に は 0 個 以 上 の フ ラ グ 文 字 が 続 く 。

#

値 は 「 別 の 形 式 」 に 変 換 さ れ る 。 o 変 換 の 場 合 、 (先 頭 文 字 が 0 に な っ て い な い 場 合 に 先 頭 に 0 を 追 加 す る こ と で ) 出 力 文 字 列 の 最 初 の 文 字 を 0 に す る 。 x と X 変 換 の 場 合 、 数 値 が 0 で な い と き に は 文 字 列 "0x" ( X 変 換 の 場 合 に は "0X") が 前 に 付 与 さ れ る 。 a , A , e , E , f , F , g , G 変 換 で は 、 小 数 点 に 続 く 数 字 が な く て も 、 出 力 に は 常 に 小 数 点 が 含 ま れ る (通 常 は 、 小 数 点 の 後 に 数 字 が 続 く 場 合 に の み 、 小 数 点 が 表 示 さ れ る )。 g と G 変 換 の 場 合 、 他 の 変 換 と は 異 な り 、 末 尾 の ゼ ロ が 変 換 結 果 か ら 削 除 さ れ な い 。 そ の 他 の 変 換 で は 、 結 果 は 未 定 義 で あ る 。

0

値 を ゼ ロ で 埋 め る 。 d , i , o , u , x , X , a , A , e , E , f , F , g , G 変 換 で は 、 変 換 し た 値 の 左 側 を 空 白 文 字 の 代 わ り に ゼ ロ で 埋 め る 。 0 と - が 両 方 と も 指 定 さ れ た 場 合 は 、 0 フ ラ グ は 無 視 さ れ る 。 精 度 が 数 値 変 換 ( d , i , o , u , x , X ) と 同 時 に 指 定 さ れ た 場 合 に は 、 0 フ ラ グ は 無 視 さ れ る 。 そ の 他 の 変 換 で は 、 動 作 は 未 定 義 で あ る 。

-

変 換 値 を フ ィ ー ル ド 境 界 で 左 揃 え に す る (デ フ ォ ル ト は 右 揃 え で あ る )。 変 換 さ れ た 値 は 左 側 で は な く 右 側 を 空 白 文 字 や ゼ ロ で 埋 め ら れ る 。 - と 0 の 両 方 が 指 定 さ れ た 場 合 に は 、 - が 優 先 さ れ る 。

’ ’

(1個 の 半 角 ス ペ ー ス ) 符 号 付 き 変 換 で 生 成 さ れ た 正 の 数 字 の 前 に 空 白 (ま た は 空 文 字 列 ) が 置 か れ る 。

+

符 号 付 き 変 換 に よ っ て 出 力 さ れ る 数 字 の 前 に 、 常 に 符 号 (+ か -) が 置 か れ る 。 デ フ ォ ル ト で は 、 符 号 は 負 の 数 字 の 場 合 の み 付 与 さ れ る 。 + と 半 角 ス ペ ー ス の 両 方 が 使 わ れ て い る 場 合 に は 、 + が 優 先 さ れ る 。

上 記 の 5 つ の フ ラ グ は C99 標 準 で 定 義 さ れ て い る 。 Single UNIX Specified で は 、 さ ら に も う 一 つ フ ラ グ 文 字 が 規 定 さ れ て い る 。

'

10進 数 変 換 ( i , d , u , f , F , g , G ) に お い て 、 ロ ケ ー ル 情 報 に 指 定 が あ れ ば 1000 単 位 の 区 切 り 文 字 を 出 力 す る ( setlocale (3) 参 照 )。 gcc (1) の 多 く の バ ー ジ ョ ン は 、 こ の オ プ シ ョ ン を 解 釈 す る こ と が で き ず 、 警 告 を 出 力 す る こ と に 注 意 せ よ 。 ( %'F は SUSv2 に は 含 ま れ て い な か っ た が 、 SUSv3 で 追 加 さ れ た 。

glibc 2.2 で は 、 さ ら に 一 つ フ ラ グ 文 字 が 追 加 さ れ て い る 。

I

10進 整 数 変 換 ( i , d , u ) に お い て 、 ロ ケ ー ル の 代 替 出 力 数 字 が あ れ ば 、 そ れ を 用 い て 出 力 す る 。 例 え ば 、 glibc 2.2.3 以 降 で は 、 ペ ル シ ア ("fa_IR") ロ ケ ー ル で ア ラ ビ ア 数 字 (Arabic-Indic digits) を 出 力 で き る 。

フ ィ ー ル ド 幅

最 小 の フ ィ ー ル ド 幅 を 指 定 す る 10進 数 の 数 値 文 字 列 (文 字 列 の 最 初 の 文 字 は ゼ ロ 以 外 )。 本 項 目 は オ プ シ ョ ン で あ る 。 変 換 さ れ た 値 の 文 字 数 が フ ィ ー ル ド 長 よ り も 少 な い 場 合 、 フ ィ ー ル ド の 左 側 を ス ペ ー ス で 埋 め る (左 揃 え の フ ラ グ が あ る 場 合 は 右 側 を 埋 め る )。 10進 数 の 文 字 列 の 代 わ り に "*" や "*m$" ( m は 10進 整 数 ) を 書 く こ と も で き る 。 "*" と "*m$" は そ れ ぞ れ 、 次 の 引 数 と m 番 目 の 引 数 を フ ィ ー ル ド 幅 と し て 使 う こ と を 指 定 す る (こ れ ら の 引 数 は int 型 で な け れ ば な ら な い )。 フ ィ ー ル ド 幅 に 負 の 数 が 指 定 さ れ た 場 合 は 、 '-' フ ラ グ と 正 の 数 の フ ィ ー ル ド 幅 と し て 扱 わ れ る 。 フ ィ ー ル ド 幅 が 小 さ か っ た り 指 定 が な か っ た り し て も 、 フ ィ ー ル ド が 切 り 詰 め ら れ る こ と は な い 。 も し 変 換 結 果 が フ ィ ー ル ド 幅 よ り も 広 か っ た 場 合 、 フ ィ ー ル ド は 変 換 結 果 が 入 る 幅 に 広 げ ら れ る 。

精 度

オ プ シ ョ ン で あ る 精 度 は 、 ピ リ オ ド ('.') と そ れ に 続 く 10進 数 と い う 形 式 で 指 定 す る (10進 数 は オ プ シ ョ ン ) 。 10進 数 の 文 字 列 の 代 わ り に "*" や "*m$" ( m は 10 進 整 数 )を 書 く こ と も で き る 。 "*" と "*m$" は そ れ ぞ れ 、 次 の 引 数 と m 番 目 の 引 数 を 精 度 と し て 使 う こ と を 指 定 す る (こ れ ら の 引 数 は int 型 で な け れ ば な ら な い )。 精 度 と し て '.' だ け が 指 定 さ れ た 場 合 、 精 度 は ゼ ロ と み な さ れ る 。 精 度 が 負 の 数 だ っ た 場 合 、 精 度 は 指 定 さ れ な か っ た も の と み な さ れ る 。 d , i , o , u , x , X 変 換 で は 、 表 示 さ れ る 最 小 の 桁 数 を 指 定 す る 。 a , A , e , E , f , F 変 換 で は 、 小 数 点 以 下 に 表 示 さ れ る 数 字 の 桁 数 を 指 定 す る 。 g と G 変 換 で は 、 有 効 数 字 の 最 大 桁 数 を 指 定 す る 。 s と S 変 換 で は 、 文 字 列 か ら 出 力 さ れ る 最 大 文 字 数 を 指 定 す る 。

長 さ 修 飾 子

「 整 数 変 換 」 と は 、 d , i , o , u , x , X 変 換 の こ と で あ る 。

hh

整 数 変 換 に 対 応 す る 引 数 が signed char か unsigned char で 、 n 変 換 に 対 応 す る 引 数 が signed char へ の ポ イ ン タ ー で あ る こ と を 示 す 。

h

整 数 変 換 に 対 応 す る 引 数 が short か unsigned short で 、 n 変 換 に 対 応 す る 引 数 が short へ の ポ イ ン タ ー で あ る こ と を 示 す 。

l

各 変 換 に 対 応 す る 引 数 が 、 整 数 変 換 で は long か unsigned long 、 n 変 換 で は long へ の ポ イ ン タ ー 、 c 変 換 で は wint_t 、 s 変 換 で は wchar_t へ の ポ イ ン タ ー で あ る こ と を 示 す 。

ll (エ ル エ ル )

整 数 変 換 に 対 応 す る 引 数 が long long か unsigned long long で 、 n 変 換 に 対 応 す る 引 数 が long long へ の ポ イ ン タ ー で あ る こ と を 示 す 。

q

A synonym for ll . This is a nonstandard extension, derived from BSD; avoid its use in new code.

L

a , A , e , E , f , F , g , G 変 換 に 対 応 す る 引 数 が long double で あ る こ と を 示 す 。 (C99 で は %LF を 使 う こ と を 認 め て い る が 、 SUSv2 で は 認 め ら れ て い な い 。 )

j

整 数 変 換 に 対 応 す る 引 数 が intmax_t か uintmax_t で 、 n 変 換 に 対 応 す る 引 数 が intmax_t へ の ポ イ ン タ ー で あ る こ と を 示 す 。

z

整 数 変 換 に 対 応 す る 引 数 が size_t か ssize_t で 、 n 変 換 に 対 応 す る 引 数 が size_t へ の ポ イ ン タ ー で あ る こ と を 示 す 。

Z

A nonstandard synonym for z that predates the appearance of z . Do not use in new code.

t

整 数 変 換 に 対 応 す る 引 数 が ptrdiff_t で 、 n 変 換 に 対 応 す る 引 数 が ptrdiff_t へ の ポ イ ン タ ー で あ る こ と を 示 す 。

SUSv3 specifies all of the above, except for those modifiers explicitly noted as being nonstandard extensions. SUSv2 specified only the length modifiers h (in hd , hi , ho , hx , hX , hn ) and l (in ld , li , lo , lx , lX , ln , lc , ls ) and L (in Le , LE , Lf , Lg , LG ).

As a nonstandard extension, the GNU implementations treats ll and L as synonyms, so that one can, for example, write llg (as a synonym for the standards-compliant Lg ) and Ld (as a synonym for the standards compliant lld ). Such usage is nonportable.

変 換 指 定 子

適 用 さ れ る 変 換 の 型 を 指 定 す る 文 字 。 変 換 指 定 子 と そ の 意 味 は 以 下 の 通 り で あ る 。

d , i

int 引 数 を 符 号 付 き 10 進 表 記 に 変 換 す る 。 精 度 指 定 が あ れ ば 、 精 度 で 指 定 し た 桁 数 は 必 ず 出 力 さ れ る 。 変 換 後 の 値 が 指 定 さ れ た 桁 数 に 足 り な い 場 合 は 、 左 側 が 0 で 埋 め ら れ る 。 デ フ ォ ル ト の 精 度 は 1 で あ る 。 0 を 表 示 し よ う と し た 時 に 、 明 示 的 に 精 度 と し て 0 が 指 定 さ れ て い る と 、 出 力 は 空 文 字 列 と な る 。

o , u , x , X

unsigned int 引 数 を 、 符 号 な し 8進 数 ( o ), 符 号 な し 10進 数 ( u ), 符 号 な し 16進 数 ( x と X ) に 変 換 す る 。 x 変 換 で は abcdef が 使 用 さ れ 、 X 変 換 で は ABCDEF が 使 用 さ れ る 。 精 度 指 定 が あ れ ば 、 精 度 で 指 定 し た 桁 数 は 必 ず 出 力 さ れ る 。 変 換 後 の 値 が 指 定 さ れ た 桁 数 に 足 り な い 場 合 は 、 左 側 が 0 で 埋 め ら れ る 。

e , E

The double argument is rounded and converted in the style [-]d . ddd e ±dd where there is one digit (which is nonzero if the argument is nonzero) before the decimal-point character and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero, no decimal-point character appears. An E conversion uses the letter E (rather than e ) to introduce the exponent. The exponent always contains at least two digits; if the value is zero, the exponent is 00.

f , F

double 引 数 を 丸 め て [-]ddd . ddd の 形 の 10進 表 現 に 変 換 す る 。 小 数 点 の 後 の 桁 数 は 、 精 度 で 指 定 さ れ た 値 と な る 。 精 度 が 指 定 さ れ て い な い 場 合 に は 6 と し て 扱 わ れ る 。 精 度 と し て 明 示 的 に 0 が 指 定 さ れ た と き に は 、 小 数 点 以 下 は 表 示 さ れ な い 。 小 数 点 を 表 示 す る 際 に は 、 小 数 点 の 前 に 少 な く と も 一 桁 は 数 字 が 表 示 さ れ る 。

(SUSv2 で は 、 F は 規 定 さ れ て お ら ず 、 無 限 や NaN に 関 す る 文 字 列 表 現 を 行 っ て も よ い こ と に な っ て い る 。 SUSv3 で は F の 規 定 が 追 加 さ れ た 。 C99 標 準 で は 、 f 変 換 で は 、 無 限 は "[-]inf" か "[-]infinity" と 表 示 し 、 NaN は 文 字 列 の 先 頭 に ‘nan’ を つ け て 表 示 す る よ う に 規 定 さ れ て い る 。 F 変 換 の 場 合 は "[-]INF", "[-]INFINITY", "NAN" と 表 示 さ れ る 。 )

g , G

double 引 数 を f か e ( G 変 換 の 場 合 は F か E ) の 形 式 に 変 換 す る 。 精 度 は 表 示 す る 桁 数 を 指 定 す る 。 精 度 が 指 定 さ れ な い 場 合 は 、 6桁 と み な さ れ る 。 精 度 が 0 の 場 合 は 、 1桁 と み な さ れ る 。 変 換 さ れ る 値 の 指 数 が 、 -4 よ り 小 さ い か 、 精 度 以 上 の 場 合 に 、 e 形 式 が 使 用 さ れ る 。 変 換 さ れ た 結 果 の 小 数 部 分 の 末 尾 の 0 は 削 除 さ れ る 。 小 数 点 が 表 示 さ れ る の は 、 小 数 点 以 下 に 数 字 が 少 な く と も 一 つ あ る 場 合 に だ け で あ る 。

a , A

(C99; not in SUSv2, but added in SUSv3) For a conversion, the double argument is converted to hexadecimal notation (using the letters abcdef) in the style [-] 0x h . hhhh p ±d; for A conversion the prefix 0X , the letters ABCDEF, and the exponent separator P is used. There is one hexadecimal digit before the decimal point, and the number of digits after it is equal to the precision. The default precision suffices for an exact representation of the value if an exact representation in base 2 exists and otherwise is sufficiently large to distinguish values of type double . The digit before the decimal point is unspecified for nonnormalized numbers, and nonzero but otherwise unspecified for normalized numbers. The exponent always contains at least one digit; if the value is zero, the exponent is 0.

c

l 修 飾 子 が な け れ ば 、 int 引 数 を unsigned char に 変 換 し て 、 そ の 結 果 に 対 応 す る 文 字 を 出 力 す る 。 l 修 飾 子 が あ れ ば 、 wint_t (ワ イ ド 文 字 ) 引 数 を 、 wcrtomb (3) 関 数 を 初 期 シ フ ト 状 態 で 呼 び 出 し て マ ル チ バ イ ト 文 字 列 に 変 換 し 、 変 換 さ れ た マ ル チ バ イ ト 文 字 列 を 出 力 す る 。

s

l 修 飾 子 が な い 場 合 、 引 数 は const char * 型 で 文 字 型 の 配 列 へ の ポ イ ン タ ー (文 字 列 へ の ポ イ ン タ ー ) で あ る こ と が 期 待 さ れ て い る 。 配 列 中 の 文 字 は 、 終 端 の ヌ ル バ イ ト ('\0') が 出 て く る ま で 出 力 さ れ る (終 端 文 字 は 出 力 さ れ な い )。 精 度 が 指 定 さ れ て い る と 、 指 定 さ れ た 字 数 以 上 は 出 力 さ れ な い 。 精 度 が 指 定 さ れ た 場 合 に は 、 終 端 バ イ ト が 存 在 す る 必 要 は な い 。 精 度 が 指 定 さ れ て い な か っ た り 、 精 度 の 値 が 配 列 の 大 き さ よ り 大 き い 場 合 に は 、 配 列 は 終 端 の ヌ ル バ イ ト を 含 ん で い な け れ ば な ら な い 。

l 修 飾 子 が 指 定 さ れ て い る 場 合 、 引 数 は const wchar_t * 型 で ワ イ ド 文 字 の 配 列 へ の ポ イ ン タ ー で あ る こ と が 期 待 さ れ て い る 。 配 列 中 の ワ イ ド 文 字 は (1文 字 毎 に wcrtomb (3) を 呼 び 出 し て ) マ ル チ バ イ ト 文 字 に 変 換 さ れ る (最 初 の ワ イ ド 文 字 の 変 換 の 前 に wcrtomb () の シ フ ト 状 態 を 初 期 状 態 に 戻 し て か ら 変 換 は 行 わ れ る )。 マ ル チ バ イ ト 文 字 へ の 変 換 は 、 文 字 列 を 終 端 す る ヌ ル ワ イ ド 文 字 が 出 て く る ま で 行 わ れ 、 終 端 ヌ ル ワ イ ド 文 字 も 含 め て 変 換 さ れ る 。 結 果 の マ ル チ バ イ ト 文 字 列 は 、 終 端 の ヌ ル バ イ ト が 出 て く る ま で 出 力 さ れ る (終 端 の ヌ ル バ イ ト は 出 力 さ れ な い )。 精 度 が 指 定 さ れ た 場 合 、 指 定 さ れ た バ イ ト 数 以 上 に は 出 力 さ れ な い 。 但 し 、 マ ル チ バ イ ト 文 字 の 一 部 分 だ け が 出 力 さ れ る こ と は な い 。 精 度 は 「 バ イ ト 」 数 を 指 定 す る も の で あ り 、 「 ワ イ ド 文 字 」 数 や 「 画 面 で の 位 置 」 を 指 定 す る も の で は な い こ と に 注 意 。 精 度 が 指 定 さ れ て い て 、 さ ら に 出 力 が 配 列 の 末 尾 に 達 す る 前 に 出 力 バ イ ト 数 が 精 度 の 値 を 超 え る 場 合 だ け は 、 配 列 は ヌ ル ワ イ ド 文 字 で 終 端 さ れ て い な く て も よ い 。 そ れ 以 外 の 場 合 は 、 必 ず 配 列 は ヌ ル ワ イ ド 文 字 で 終 端 さ れ て い な け れ ば な ら な い 。

C

(C99, C11 に は な い が SUSv2, SUSv3, SUSv4 に は あ る ) lc と 同 じ 。 使 っ て は な ら な い 。

S

(C99, C11 に は な い が SUSv2, SUSv3, SUSv4 に は あ る ) ls と 同 じ 。 使 っ て は な ら な い 。

p

void * ポ イ ン タ ー 引 数 を ( %#x や %#lx の よ う な ) 16 進 数 で 出 力 す る 。

n

The number of characters written so far is stored into the integer pointed to by the corresponding argument. That argument shall be an int * , or variant whose size matches the (optionally) supplied integer length modifier. No argument is converted. (This specifier is not supported by the bionic C library.) The behavior is undefined if the conversion specification includes any flags, a field width, or a precision.

m

(glibc で の 拡 張 ; uClibc と musl で 対 応 ) strerror(errno) の 出 力 を 表 示 す る 。 引 数 は 必 要 な い 。

%

'%' 文 字 を 出 力 す る 。 変 換 さ れ る 引 数 は 無 い 。 変 換 指 定 全 体 を 書 く と "%%" と な る 。

返 り 値

成 功 時 に は 、 上 記 の 関 数 は 書 き 込 ま れ た 文 字 数 を 返 す (文 字 列 の 最 後 を 示 す た め に 使 用 す る ヌ ル バ イ ト は 数 に 含 ま れ な い )。

snprintf () と vsnprintf () は 、 size バ イ ト を 越 え る 文 字 数 を 書 き 込 ま な い ( size に は 文 字 列 を 終 端 す る ヌ ル バ イ ト ('\0') も 含 ま れ る )。 こ の 制 限 に よ っ て 出 力 が 切 り 詰 め ら れ た 場 合 に は 、 も し 十 分 な ス ペ ー ス が あ れ ば 書 き 込 ま れ た で あ ろ う 文 字 の 個 数 (文 字 列 を 終 端 す る ヌ ル バ イ ト を 除 く ) を 返 す 。 従 っ て 、 返 り 値 が size 以 上 だ っ た 場 合 、 出 力 が 切 り 詰 め ら れ た こ と を 意 味 す る (後 述 の 注 意 も 参 照 の こ と )。

エ ラ ー が 発 生 し た 場 合 は 、 負 の 数 を 返 す 。

属 性

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

Image grohtml-25196-1.png

準 拠

fprintf (), printf (), sprintf (), vprintf (), vfprintf (), vsprintf (): POSIX.1-2001, POSIX.1-2008, C89, C99.

snprintf (), vsnprintf (): POSIX.1-2001, POSIX.1-2008, C99.

dprintf () と vdprintf () は 、 ど ち ら も 元 は GNU に よ る 拡 張 で あ っ た が 、 POSIX.1-2008 で 標 準 化 さ れ た 。

snprintf () の 返 り 値 を 見 る と 、 SUSv2 と C99 標 準 は 互 い に 矛 盾 し て い る 。 SUSv2 で は 、 snprintf () が size =0 で 呼 び 出 さ れ た 場 合 、 1 未 満 の 値 を 何 か 返 り 値 と す る よ う に 規 定 し て い る 。 一 方 C99 で は 、 こ の よ う な 場 合 str を NULL と し 、 返 り 値 と し て (通 常 通 り ) 出 力 バ ッ フ ァ ー が 十 分 な 大 き さ が あ っ た 場 合 に 出 力 さ れ る で あ ろ う 文 字 数 を 返 す 。 POSIX.1-2001 や そ れ 以 降 で は C99 の snprintf () の 規 定 に あ わ せ た も の と な っ て い る 。

glibc 2.1 で は 、 長 さ 修 飾 子 hh , j , t , z と 変 換 文 字 a , A が 追 加 さ れ た 。

glibc 2.2 で は 、 C99 で 規 定 さ れ た 意 味 で の 変 換 文 字 F と フ ラ グ 文 字 I が 追 加 さ れ た 。

注 意

テ キ ス ト を buf に 追 加 す る の に 、 軽 率 に も 次 の よ う な コ ー ド を 使 っ て い る プ ロ グ ラ ム が あ る 。

sprintf(buf, "%s some further text", buf);

し か し な が ら 、 標 準 規 格 で は 、 sprintf (), snprintf (), vsprintf (), vsnprintf () の 呼 び 出 し に お い て 、 コ ピ ー 元 と コ ピ ー 先 の バ ッ フ ァ ー が 重 な っ て い た 場 合 の 結 果 は 不 定 で あ る 、 と 明 記 さ れ て い る 。 使 用 す る gcc (1) の バ ー ジ ョ ン や 指 定 し た コ ン パ イ ラ の オ プ シ ョ ン 次 第 で は 、 上 記 の よ う な 呼 び 出 し で 、 期 待 し た 結 果 が 得 ら れ 「 な い 」 こ と が あ る 。

glibc の snprintf () と vsnprintf () の 実 装 は 、 バ ー ジ ョ ン 2.1 以 降 は C99 標 準 に 準 拠 し て お り 、 上 記 の 通 り の 動 作 を す る 。 glibc 2.0.6 ま で は 、 出 力 が 切 り 詰 め ら れ た 場 合 は -1 を 返 す 。

バ グ

sprintf () と vsprintf () は 勝 手 に 十 分 に 長 い 文 字 列 領 域 が あ る と 仮 定 す る の で 、 呼 び 出 し 側 は 実 際 の 領 域 か ら あ ふ れ な い よ う に 注 意 し な け れ ば な ら な い 。 し か し 、 こ れ を 保 証 す る こ と が 不 可 能 な 場 合 が 多 い 。 生 成 さ れ る 文 字 列 の 長 さ は ロ ケ ー ル 依 存 で あ り 、 予 測 が 難 し い こ と に 注 意 。 代 わ り に snprintf () と vsnprintf () (ま た は asprintf (3) と vasprintf (3)) を 使 う こ と 。

printf( foo ); の よ う な コ ー ド は し ば し ば バ グ を 引 き 起 こ す 。 な ぜ な ら foo に % 文 字 が 含 ま れ て る か も し れ な い か ら で あ る 。 foo が 信 頼 で き な い ユ ー ザ ー 入 力 か ら 作 ら れ て い る 場 合 に は 、 そ の 中 に %n が 含 ま れ て い る こ と が あ り 、 printf () 呼 び 出 し 時 に メ モ リ ー へ の 書 き 込 み が 起 こ り 、 セ キ ュ リ テ ィ ー ホ ー ル を 作 る こ と に な る か も し れ な い 。

例

Pi を 5 桁 で 出 力 す る 。

#include <math.h>
#include <stdio.h>
fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

日 付 と 時 間 を "Sunday, July 3, 10:02" の 形 式 で 出 力 す る 。 ( weekday と month は 文 字 列 へ の ポ イ ン タ ー で あ る )

#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",

weekday, month, day, hour, min);

日 - 月 - 年 の 順 序 で 表 示 を 行 う 国 も 多 い 。 従 っ て 、 国 際 版 で は 書 式 で 指 定 さ れ た 順 番 で 引 数 を 表 示 で き な け れ ば な ら な い 。

#include <stdio.h>
fprintf(stdout, format,

weekday, month, day, hour, min);

format は ロ ケ ー ル に 依 存 し て お り 、 引 数 の 順 番 を 変 え る こ と も で き る 。 format が

"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"

で あ れ ば 、 "Sonntag, 3. Juli, 10:02" と い う 結 果 に な る 。

十 分 に 大 き な 文 字 列 領 域 を 確 保 し て 、 そ こ に メ ッ セ ー ジ を 格 納 す る に は (glibc 2.0 と glibc 2.1 の 両 方 で 正 し く 動 作 す る コ ー ド ):

#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>

char *
make_message(const char *fmt, ...)
{
int n = 0;
size_t size = 0;
char *p = NULL;
va_list ap;

/* Determine required size */

va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);

if (n < 0)
return NULL;

/* One extra byte for '\0' */

size = (size_t) n + 1;
p = malloc(size);
if (p == NULL)
return NULL;

va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);

if (n < 0) {
free(p);
return NULL;
}

return p;
}

バ ー ジ ョ ン 2.0.6 よ り 前 の glibc で 切 り 詰 め が 起 こ っ た 場 合 、 切 り 詰 め は 適 切 に 処 理 さ れ ず 、 エ ラ ー と し て 扱 わ れ る 。

関 連 項 目

printf (1), asprintf (3), puts (3), scanf (3), setlocale (3), strfromd (3), wcrtomb (3), wprintf (3), locale (5)

こ の 文 書 に つ い て

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