名 前
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf − 指 定 さ れ た 書 式 に 変 換 し て 出 力 を 行 う
書 式
#include <stdio.h>
int
printf(const char *format, ...);
int fprintf(FILE *stream, 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 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():
_BSD_SOURCE || _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L; ま た は cc −std=c99
説 明
printf() 関 数 グ ル ー プ は 、 以 下 で 述 べ る よ う に 、 format に 従 っ て 出 力 を 生 成 す る も の で あ る 。 printf() と vprintf() は 出 力 を stdout (標 準 出 力 ス ト リ ー ム ) に 書 き 出 す 。 fprintf() と vfprintf() は 出 力 を 指 定 さ れ た 出 力 stream に 書 き 出 す 。 sprintf(), snprintf(), vsprintf(), vsnprintf() は 出 力 を 文 字 列 str に 書 き 込 む 。
snprintf() と vsnprintf() は 最 大 で size バ イ ト を str に 書 き 込 む (size に は 文 字 列 を 終 端 す る ヌ ル バ イ ト ('\0') も を 含 ま れ る )。
vprintf(), vfprintf(), vsprintf(), vsnprintf() の 各 関 数 は そ れ ぞ れ printf(), fprintf(), sprintf(), snprintf(), の 各 関 数 と 等 価 で あ り 、 可 変 数 引 き 数 の 代 わ り に va_list を 引 き 数 と し て 呼 び 出 さ れ る 点 だ け が 異 な る 。 こ れ ら の 関 数 で は va_end マ ク ロ は 呼 び 出 さ れ な い 。 こ れ ら の 関 数 は va_arg を 呼 び 出 す の で 、 呼 び 出 し 後 の ap の 値 は 未 定 義 で あ る 。 stdarg(3) を 参 照 の こ と 。 こ れ ら の 8 つ の 関 数 は format 文 字 列 の 制 御 に 従 っ て 出 力 を 書 き 出 す 。 format 文 字 列 は 、 こ れ に 続 く 引 き 数 (ま た は stdarg(3) の 可 変 長 引 き 数 機 構 を 使 っ て ア ク セ ス で き る 引 き 数 ) を ど の よ う に 変 換 し て 出 力 す る か を 指 定 す る 。
C99 と POSIX.1−2001 で は 、 sprintf(), snprintf(), vsprintf(), vsnprintf() の 呼 び 出 し で 、 範 囲 が 重 複 す る オ ブ ジ ェ ク ト 間 で コ ピ ー が 発 生 す る 場 合 の 結 果 は 不 定 で あ る と 規 定 さ れ て い る (例 え ば 、 出 力 先 の 文 字 列 と 入 力 さ れ た 引 き 数 の 一 つ が 同 じ バ ッ フ ァ ー を 参 照 し て い る 場 合 な ど で あ る )。 「 注 意 」 の 節 を 参 照 。
Return Values 成 功 時 に は 、 上 記 の 関 数 は 書 き 込 ま れ た 文 字 数 を 返 す (文 字 列 の 最 後 を 示 す た め に 使 用 す る ヌ ル バ イ ト は 数 に 含 ま れ な い )。
snprintf() と vsnprintf() は 、 size バ イ ト を 越 え る 文 字 数 を 書 き 込 ま な い (size に は 文 字 列 を 終 端 す る ヌ ル バ イ ト ('\0') も 含 ま れ る )。 こ の 制 限 に よ っ て 出 力 が 切 り 詰 め ら れ た 場 合 に は 、 も し 十 分 な ス ペ ー ス が あ れ ば 書 き 込 ま れ た で あ ろ う 文 字 の 個 数 (文 字 列 を 終 端 す る ヌ ル バ イ ト を 除 く ) を 返 す 。 従 っ て 、 返 り 値 が size 以 上 だ っ た 場 合 、 出 力 が 切 り 詰 め ら れ た こ と を 意 味 す る (後 述 の 注 意 も 参 照 の こ と )。 エ ラ ー が 発 生 し た 場 合 は 、 負 の 数 を 返 す 。 フ ォ ー マ ッ ト 文 字 列 の フ ォ ー マ ッ ト フ ォ ー マ ッ ト 文 字 列 は 文 字 の 列 で 、 (も し あ る な ら ) 初 期 シ フ ト 状 態 で 始 ま り 、 初 期 シ フ ト 状 態 で 終 わ る 。 フ ォ ー マ ッ ト 用 の 文 字 列 は 0 個 以 上 の 命 令 (directives) に よ っ て 構 成 さ れ る 。 命 令 に は 、 通 常 文 字 と 変 換 指 定 (conversion specifications) が あ る 。 通 常 文 字 は % 以 外 の 文 字 で 、 出 力 ス ト リ ー ム に そ の ま ま コ ピ ー さ れ る 。 変 換 指 定 は 、 そ れ ぞ れ が 0 個 以 上 の 引 き 数 を 取 る 。 各 変 換 指 定 は 文 字 % で 始 ま り 、 変 換 指 定 子 (conversion specifier) で 終 わ る 。 % と 変 換 指 定 子 の 間 に は 、 0 個 以 上 の フ ラ グ 、 最 小 フ ィ ー ル ド 幅 、 精 度 、 長 さ 修 飾 子 を (こ の 順 序 で ) 置 く こ と が で き る 。 引 き 数 は (型 の 格 上 げ の 後 は ) 変 換 指 定 子 が 表 す 型 と 正 確 に 対 応 し な け れ ば な ら な い 。 デ フ ォ ル ト で は 、 '*' や 変 換 指 定 子 が 出 て く る 毎 に 次 の 引 き 数 を 要 求 さ れ 、 引 き 数 は 指 定 さ れ た 順 序 で 使 用 さ れ て い く (指 定 さ れ た 引 き 数 の 個 数 が 不 十 分 な ら エ ラ ー と な る )。 ま た 、 引 き 数 が 必 要 な 箇 所 で '%' の 代 わ り に "%m$"、 '*'の 代 わ り に "*m$" と 書 く こ と で 、 明 示 的 に ど の 引 き 数 を 使 用 す る か を 指 定 す る こ と も で き る 。 こ こ で 10進 の 整 数 m は 希 望 の 引 き 数 の 引 き 数 リ ス ト で の 位 置 を 示 す (最 初 の 引 き 数 の 番 号 が 1 で あ る )。 従 っ て 、
printf("%*d", width, num); と
printf("%2$*1$d", width, num); は 等 価 で あ る 。 二 番 目 の 書 き 方 で は 同 じ 引 き 数 を 繰 り 返 し 参 照 す る こ と が で き る 。 C99 標 準 に は 、 Single UNIX Specification 由 来 の '$' を 使 っ た 書 き 方 は 含 ま れ て い な い 。 '$' を 使 っ た ス タ イ ル を 使 う と 、 引 き 数 を 取 る 変 換 及 び 幅 と 精 度 の 引 き 数 を 全 て こ の ス タ イ ル で 指 定 し な け れ ば な ら な い が 、 引 き 数 を 消 費 し な い "%%" フ ォ ー マ ッ ト と 混 ざ っ て い る か も し れ な い 。 '$' で 指 定 さ れ る 引 き 数 の 番 号 に 空 き が あ っ て は な ら な い 。 例 え ば 、 も し 引 き 数 1 と 3 が 指 定 さ れ る と 、 引 き 数 2 も フ ォ ー マ ッ ト 文 字 列 の ど こ か で 指 定 さ れ な け れ ば な ら な い 。 数 値 変 換 に は 小 数 点 や 1000 単 位 の 区 切 り 文 字 を 使 う も の も あ る 。 実 際 に ど の 文 字 を 使 う か は ロ ケ ー ル の LC_NUMERIC に よ る 。 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 で は 、 さ ら に も う 一 つ フ ラ グ 文 字 が 規 定 さ れ て い る 。 '
glibc 2.2 で は 、 さ ら に 一 つ フ ラ グ 文 字 が 追 加 さ れ て い る 。
フ ィ ー ル ド 幅 最 小 の フ ィ ー ル ド 幅 を 指 定 す る 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 変 換 の こ と で あ る 。
変 換 に 対 応 す る 引 き 数 が signed char へ の ポ イ ン タ ー で あ る こ と を 示 す 。
n 変 換 に 対 応 す る 引 き 数 が short int へ の ポ イ ン タ ー で あ る こ と を 示 す 。
int、 n 変 換 で は long long int へ の ポ イ ン タ ー 、 c 変 換 で は wint_t、 s 変 換 で は wchar_t へ の ポ イ ン タ ー で あ る こ と を 示 す 。 ll (エ ル エ ル ) 整 数 変 換 に 対 応 す る 引 き 数 が long long int か unsigned long long int で 、 n 変 換 に 対 応 す る 引 き 数 が long int へ の ポ イ ン タ ー で あ る こ と を 示 す 。
|