release/man3/printf.3

   1 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" Earlier versions of this page influenced the present text.
   4 .\" It was derived from a Berkeley page with version
   5 .\"       @(#)printf.3    6.14 (Berkeley) 7/30/91
   6 .\" converted for Linux by faith@cs.unc.edu, updated by
   7 .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
   8 .\"
   9 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
  10 .\" This is free documentation; you can redistribute it and/or
  11 .\" modify it under the terms of the GNU General Public License as
  12 .\" published by the Free Software Foundation; either version 2 of
  13 .\" the License, or (at your option) any later version.
  14 .\"
  15 .\" The GNU General Public License's references to "object code"
  16 .\" and "executables" are to be interpreted as the output of any
  17 .\" document formatting or typesetting system, including
  18 .\" intermediate and printed output.
  19 .\"
  20 .\" This manual is distributed in the hope that it will be useful,
  21 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  22 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23 .\" GNU General Public License for more details.
  24 .\"
  25 .\" You should have received a copy of the GNU General Public
  26 .\" License along with this manual; if not, see
  27 .\" <http://www.gnu.org/licenses/>.
  28 .\" %%%LICENSE_END
  29 .\"
  30 .\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99.
  31 .\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes
  32 .\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes
  33 .\"
  34 .\"*******************************************************************
  35 .\"
  36 .\" This file was generated with po4a. Translate the source file.
  37 .\"
  38 .\"*******************************************************************
  39 .\"
  40 .\" Japanese Version Copyright (c) 1997 YOSHINO Takashi all rights reserved.
  41 .\" Translated 1998-02-17, YOSHINO Takashi <yoshino@civil.jcn.nihon-u.ac.jp>
  42 .\" Updated 2000-10-02, Kentaro Shirakata <argrath@ub32.org>
  43 .\" Updated 2001-01-29, Kentaro Shirakata <argrath@ub32.org>
  44 .\" Updated 2002-01-03, Kentaro Shirakata <argrath@ub32.org>
  45 .\" Updated 2002-10-17, Kentaro Shirakata <argrath@ub32.org>
  46 .\" Updated 2005-03-15, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  47 .\" Updated 2006-07-20, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  48 .\" Updated 2008-02-10, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.77
  49 .\" Updated 2009-03-03, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.19
  50 .\" Updated 2012-05-29, Akihiro MOTOKI <amotoki@gmail.com>
  51 .\" Updated 2013-05-06, Akihiro MOTOKI <amotoki@gmail.com>
  52 .\" Updated 2013-07-22, Akihiro MOTOKI <amotoki@gmail.com>
  53 .\"
  54 .TH PRINTF 3 2014\-07\-08 GNU "Linux Programmer's Manual"
  55 .SH 名前
  56 printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf \-
  57 指定された書式に変換して出力を行う
  58 .SH 書式
  59 \fB#include <stdio.h>\fP
  60 .sp
  61 \fBint printf(const char *\fP\fIformat\fP\fB, ...);\fP
  62 .br
  63 \fBint fprintf(FILE *\fP\fIstream\fP\fB, const char *\fP\fIformat\fP\fB, ...);\fP
  64 .br
  65 \fBint sprintf(char *\fP\fIstr\fP\fB, const char *\fP\fIformat\fP\fB, ...);\fP
  66 .br
  67 \fBint snprintf(char *\fP\fIstr\fP\fB, size_t \fP\fIsize\fP\fB, const char *\fP\fIformat\fP\fB,
  68 \&...);\fP
  69 .sp
  70 \fB#include <stdarg.h>\fP
  71 .sp
  72 \fBint vprintf(const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
  73 .br
  74 \fBint vfprintf(FILE *\fP\fIstream\fP\fB, const char *\fP\fIformat\fP\fB, va_list
  75 \fP\fIap\fP\fB);\fP
  76 .br
  77 \fBint vsprintf(char *\fP\fIstr\fP\fB, const char *\fP\fIformat\fP\fB, va_list
  78 \fP\fIap\fP\fB);\fP
  79 .br
  80 \fBint vsnprintf(char *\fP\fIstr\fP\fB, size_t \fP\fIsize\fP\fB, const char
  81 *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
  82 .sp
  83 .in -4n
  84 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  85 .in
  86 .sp
  87 .ad l
  88 \fBsnprintf\fP(), \fBvsnprintf\fP():
  89 .RS 4
  90 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
  91 _POSIX_C_SOURCE\ >=\ 200112L;
  92 .br
  93 または \fIcc \-std=c99\fP
  94 .RE
  95 .ad
  96 .SH 説明
  97 \fBprintf\fP()  関数グループは、以下で述べるように、 \fIformat\fP に従って出力を生成するものである。 \fBprintf\fP()  と
  98 \fBvprintf\fP()  は出力を \fIstdout\fP (標準出力ストリーム) に書き出す。 \fBfprintf\fP()  と
  99 \fBvfprintf\fP()  は出力を指定された出力 \fIstream\fP に書き出す。 \fBsprintf\fP(), \fBsnprintf\fP(),
 100 \fBvsprintf\fP(), \fBvsnprintf\fP()  は出力を文字列 \fIstr\fP に書き込む。
 101 .PP
 102 \fBsnprintf\fP()  と \fBvsnprintf\fP()  は最大で \fIsize\fP バイトを \fIstr\fP に書き込む (\fIsize\fP
 103 には文字列を終端するヌルバイト (\(aq\e0\(aq) もを含まれる)。
 104 .PP
 105 \fBvprintf\fP(), \fBvfprintf\fP(), \fBvsprintf\fP(), \fBvsnprintf\fP()  の各関数はそれぞれ
 106 \fBprintf\fP(), \fBfprintf\fP(), \fBsprintf\fP(), \fBsnprintf\fP(),
 107 の各関数と等価であり、可変数引き数の代わりに \fIva_list\fP を引き数として呼び出される点だけが異なる。 これらの関数では \fIva_end\fP
 108 マクロは呼び出されない。 これらの関数は \fIva_arg\fP を呼び出すので、呼び出し後の \fIap\fP の値は未定義である。 \fBstdarg\fP(3)
 109 を参照のこと。
 110 .PP
 111 これらの 8 つの関数は \fIformat\fP 文字列の制御に従って出力を書き出す。 \fIformat\fP 文字列は、これに続く引き数 (または
 112 \fBstdarg\fP(3)  の可変長引き数機構を使ってアクセスできる引き数)  をどのように変換して出力するかを指定する。
 113
 114 C99 と POSIX.1\-2001 では、 \fBsprintf\fP(), \fBsnprintf\fP(), \fBvsprintf\fP(),
 115 \fBvsnprintf\fP()  の呼び出しで、範囲が重複するオブジェクト間でコピーが発生する場合の 結果は不定であると規定されている
 116 (例えば、出力先の文字列と入力された 引き数の一つが同じバッファを参照している場合などである)。 「注意」の節を参照。
 117 .SS "Return Values"
 118 成功時には、上記の関数は書き込まれた文字数を返す (文字列の最後を示すために使用するヌルバイトは数に含まれない)。
 119
 120 \fBsnprintf\fP()  と \fBvsnprintf\fP()  は、 \fIsize\fP バイトを越える文字数を書き込まない (\fIsize\fP
 121 には文字列を終端するヌルバイト (\(aq\e0\(aq) も含まれる)。 この制限によって出力が切り詰められた場合には、
 122 もし十分なスペースがあれば書き込まれたであろう文字の個数 (文字列を終端するヌルバイトを除く) を返す。 従って、返り値が \fIsize\fP
 123 以上だった場合、出力が切り詰められたことを意味する (後述の注意も参照のこと)。
 124
 125 エラーが発生した場合は、負の数を返す。
 126 .SS フォーマット文字列のフォーマット
 127 フォーマット文字列は文字の列で、 (もしあるなら) 初期シフト状態で始まり、初期シフト状態で終わる。 フォーマット用の文字列は 0 個以上の命令
 128 (directives) によって構成される。 命令には、通常文字と変換指定 (conversion specifications) がある。
 129 通常文字は \fB%\fP 以外の文字で、出力ストリームにそのままコピーされる。 変換指定は、それぞれが 0 個以上の引き数を取る。 各変換指定は文字
 130 \fB%\fP で始まり、 \fI変換指定子 (conversion specifier)\fP で終わる。 \fB%\fP と変換指定子の間には、0 個以上の
 131 \fIフラグ 、\fP 最小 \fIフィールド幅 、\fP \fI精度 、\fP \fI長さ修飾子\fP を (この順序で) 置くことができる。
 132
 133 引き数は (型の格上げの後は) 変換指定子が表す型と正確に対応しなければならない。 デフォルトでは、\(aq*\(aq
 134 や変換指定子が出てくる毎に次の引き数を要求され、 引き数は指定された順序で使用されていく (指定された引き数の個数が不十分ならエラーとなる)。
 135 また、引き数が必要な箇所で \(aq%\(aq の代わりに "%m$"、 \(aq*\(aqの代わりに "*m$" と書くことで、
 136 明示的にどの引き数を使用するかを指定することもできる。 ここで 10進の整数 m は希望の引き数の引き数リストでの位置を示す (最初の引き数の番号が 1
 137 である)。 従って、
 138 .in +4n
 139 .nf
 140
 141 printf("%*d", width, num);
 142
 143 .fi
 144 .in
 145 と
 146 .in +4n
 147 .nf
 148
 149 printf("%2$*1$d", width, num);
 150
 151 .fi
 152 .in
 153 は等価である。 二番目の書き方では同じ引き数を繰り返し参照することができる。 C99 標準には、 Single UNIX Specification
 154 由来の \(aq$\(aq を使った書き方は含まれていない。 \(aq$\(aq を使ったスタイルを使うと、引き数を取る変換及び幅と精度の引き数を
 155 全てこのスタイルで指定しなければならないが、 引き数を消費しない "%%" フォーマットと混ざっているかもしれない。 \(aq$\(aq
 156 で指定される引き数の番号に空きがあってはならない。 例えば、もし引き数 1 と 3 が指定されると、引き数 2 もフォーマット文字列のどこかで
 157 指定されなければならない。
 158
 159 数値変換には小数点や 1000 単位の区切り文字を使うものもある。 実際にどの文字を使うかはロケールの \fBLC_NUMERIC\fP による。 POSIX
 160 ロケールでは小数点に \(aq.\(aq を用い、 区切り文字は使わない。 従って、
 161 .in +4n
 162 .nf
 163
 164 printf("%\(aq.2f", 1234567.89);
 165
 166 .fi
 167 .in
 168 は、 POSIX ロケールでは "1234567.89" 、 nl_NL ロケールでは "1234567,89"、 da_DK ロケールでは
 169 "1.234.567,89" となる。
 170 .SS フラグ文字
 171 % 文字の後ろには 0 個以上のフラグ文字が続く。
 172 .TP
 173 \fB#\fP
 174 値は「別の形式」に変換される。 \fBo\fP 変換の場合、(先頭文字が 0 になっていない場合に先頭に 0 を追加することで)  出力文字列の最初の文字を
 175 0 にする。 \fBx\fP と \fBX\fP 変換の場合、数値が 0 でないときには文字列 "0x" (\fBX\fP 変換の場合には "0X") が前に付与される。
 176 \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, \fBg\fP, \fBG\fP 変換では、 小数点に続く数字がなくても、
 177 出力には常に小数点が含まれる (通常は、小数点の後に数字が続く場合にのみ、 小数点が表示される)。 \fBg\fP と \fBG\fP
 178 変換の場合、他の変換とは異なり、末尾のゼロが変換結果から削除されない。 その他の変換では、結果は未定義である。
 179 .TP
 180 \fB\&0\fP
 181 値をゼロで埋める。 \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP,
 182 \fBF\fP, \fBg\fP, \fBG\fP 変換では、変換した値の左側を空白文字の代わりにゼロで埋める。 \fB\&0\fP と \fB\-\fP が両方とも指定された場合は、
 183 \fB\&0\fP フラグは無視される。 精度が数値変換 (\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP)
 184 と同時に指定された場合には、 \fB\&0\fP フラグは無視される。 その他の変換では、動作は未定義である。
 185 .TP
 186 \fB\-\fP
 187 変換値をフィールド境界で左揃えにする (デフォルトは右揃えである)。 変換された値は 左側ではなく右側を空白文字やゼロで埋められる。 \fB\-\fP と
 188 \fB\&0\fP の両方が指定された場合には、 \fB\-\fP が優先される。
 189 .TP
 190 \&\fB' '\fP
 191 (1個の半角スペース)  符号付き変換で生成された正の数字の前に空白 (または空文字列) が置かれる。
 192 .TP
 193 \fB+\fP
 194 符号付き変換によって出力される数字の前に、常に符号 (+ か \-) が置かれる。 デフォルトでは、符号は負の数字の場合のみ付与される。 \fB+\fP
 195 と半角スペースの 両方が使われている場合には、 \fB+\fP が優先される。
 196 .PP
 197 上記の 5 つのフラグは C99 標準で定義されている。 Single UNIX Specified では、さらにもう一つフラグ文字が規定されている。
 198 .TP
 199 \fB\(aq\fP
 200 10進数変換 (\fBi\fP, \fBd\fP, \fBu\fP, \fBf\fP, \fBF\fP, \fBg\fP, \fBG\fP)  において、ロケール情報に指定があれば 1000
 201 単位の区切り文字を出力する。 \fBgcc\fP(1)  の多くのバージョンは、このオプションを解釈することができず、 警告を出力することに注意せよ。
 202 (\fI%\(aqF\fP は SUSv2 には含まれていなかったが、 SUSv3 で追加された。
 203 .PP
 204 glibc 2.2 では、さらに一つフラグ文字が追加されている。
 205 .TP
 206 \fBI\fP
 207 .\" outdigits keyword in locale file
 208 10進整数変換 (\fBi\fP, \fBd\fP, \fBu\fP)  において、ロケールの代替出力数字があれば、それを用いて出力する。 例えば、 glibc
 209 2.2.3 以降では、ペルシア ("fa_IR") ロケールで アラビア数字 (Arabic\-Indic digits) を出力できる。
 210 .SS フィールド幅
 211 最小のフィールド幅を指定する 10進数の数値文字列 (文字列の最初の文字は ゼロ以外)。本項目はオプションである。
 212 変換された値の文字数がフィールド長よりも少ない場合、 フィールドの左側をスペースで埋める (左揃えのフラグがある場合は右側を埋める)。
 213 10進数の文字列の代わりに "*" や "*m$" (\fIm\fP は 10進整数) を書くこともできる。 "*" と "*m$" はそれぞれ、次の引き数と
 214 \fIm\fP 番目の引き数をフィールド幅として 使うことを指定する (これらの引き数は \fIint\fP 型でなければならない)。
 215 フィールド幅に負の数が指定された場合は、 \(aq\-\(aq フラグと正の数のフィールド幅として扱われる。
 216 フィールド幅が小さかったり指定がなかったりしても、フィールドが切り詰められる ことはない。もし変換結果がフィールド幅よりも広かった場合、
 217 フィールドは変換結果が入る幅に広げられる。
 218 .SS 精度
 219 オプションである精度は、ピリオド (\(aq.\(aq) とそれに続く10進数という 形式で指定する (10進数はオプション) 。
 220 10進数の文字列の代わりに "*" や "*m$" (m は 10 進整数)を書くこともできる。 "*" と "*m$" はそれぞれ、次の引き数と m
 221 番目の引き数を精度として 使うことを指定する (これらの引き数は \fIint\fP 型でなければならない)。 精度として \(aq.\(aq
 222 だけが指定された場合、 精度はゼロとみなされる。 精度が負の数だった場合、 精度は指定されなかったものとみなされる。 \fBd\fP, \fBi\fP, \fBo\fP,
 223 \fBu\fP, \fBx\fP, \fBX\fP 変換では、表示される最小の桁数を指定する。 \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP
 224 変換では、小数点以下に表示される数字の桁数を指定する。 \fBg\fP と \fBG\fP 変換では、有効数字の最大桁数を指定する。 \fBs\fP と \fBS\fP
 225 変換では、文字列から出力される最大文字数を指定する。
 226 .SS 長さ修飾子
 227 「整数変換」とは、 \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP 変換のことである。
 228 .TP
 229 \fBhh\fP
 230 整数変換に対応する引き数が \fIsigned char\fP か \fIunsigned char\fP で、 \fBn\fP 変換に対応する引き数が \fIsigned
 231 char\fP へのポインタであることを示す。
 232 .TP
 233 \fBh\fP
 234 整数変換に対応する引き数が \fIshort int\fP か \fIunsigned short int\fP で、 \fBn\fP 変換に対応する引き数が
 235 \fIshort int\fP へのポインタであることを示す。
 236 .TP
 237 \fBl\fP
 238 各変換に対応する引き数が、 整数変換では \fIlong int\fPか \fIunsigned long int\fP、 \fBn\fP 変換では \fIlong
 239 long int\fP へのポインタ、 \fBc\fP 変換では \fIwint_t\fP、 \fBs\fP 変換では \fIwchar_t\fP へのポインタであることを示す。
 240 .TP
 241 \fBll\fP (エルエル)
 242 整数変換に対応する引き数が \fIlong long int\fP か \fIunsigned long long int\fP で、 \fBn\fP
 243 変換に対応する引き数が \fIlong int\fP へのポインタであることを示す。
 244 .TP
 245 \fBL\fP
 246 .\" .TP
 247 .\" .B q
 248 .\" ("quad". 4.4BSD and Linux libc5 only.
 249 .\" Don't use.)
 250 \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, \fBg\fP, \fBG\fP 変換に対応する引き数が \fIlong double\fP
 251 であることを示す。 (C99 では %LF を使うことを認めているが、SUSv2 では認められていない。) これは \fBll\fP の同義語である。
 252 .TP
 253 \fBj\fP
 254 整数変換に対応する引き数が \fIintmax_t\fP か \fIuintmax_t\fP で、 \fBn\fP 変換に対応する引き数が \fIintmax_t\fP
 255 へのポインタであることを示す。
 256 .TP
 257 \fBz\fP
 258 .\" (Linux libc5 has
 259 .\" .B Z
 260 .\" with this meaning.
 261 .\" Don't use it.)
 262 整数変換に対応する引き数が \fIsize_t\fP か \fIssize_t\fP で、 \fBn\fP 変換に対応する引き数が \fIsize_t\fP
 263 へのポインタであることを示す。
 264 .TP
 265 \fBt\fP
 266 整数変換に対応する引き数が \fIptrdiff_t\fP で、 \fBn\fP 変換に対応する引き数が \fIptrdiff_t\fP へのポインタであることを示す。
 267 .PP
 268 SUSv3 では上記のすべてが規定されている。 SUSv2 で規定されていたのは、 長さ修飾子 \fBh\fP (\fBhd\fP, \fBhi\fP, \fBho\fP,
 269 \fBhx\fP, \fBhX\fP, \fBhn\fP), \fBl\fP (\fBld\fP, \fBli\fP, \fBlo\fP, \fBlx\fP, \fBlX\fP, \fBln\fP, \fBlc\fP,
 270 \fBls\fP), \fBL\fP (\fBLe\fP, \fBLE\fP, \fBLf\fP, \fBLg\fP, \fBLG\fP)  だけであった。
 271 .SS 変換指定子
 272 適用される変換の型を指定する文字。 変換指定子とその意味は以下の通りである。
 273 .TP
 274 \fBd\fP, \fBi\fP
 275 \fIint\fP 引き数を符号付き 10 進表記に変換する。 精度指定があれば、精度で指定した桁数は必ず出力される。変換後の値が
 276 指定された桁数に足りない場合は、左側が 0 で埋められる。 デフォルトの精度は 1 である。 0 を表示しようとした時に、明示的に精度として 0
 277 が指定されていると、 出力は空文字列となる。
 278 .TP
 279 \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP
 280 \fIunsigned int\fP 引き数を、 符号なし8進数 (\fBo\fP), 符号なし10進数 (\fBu\fP), 符号なし16進数 (\fBx\fP と
 281 \fBX\fP)  に変換する。 \fBx\fP 変換では \fBabcdef\fP が使用され、 \fBX\fP 変換では \fBABCDEF\fP が使用される。
 282 精度指定があれば、精度で指定した桁数は必ず出力される。変換後の値が 指定された桁数に足りない場合は、左側が 0 で埋められる。
 283 .TP
 284 \fBe\fP, \fBE\fP
 285 \fIdouble\fP 引き数を丸めて [\-]d\fB\&.\fPddd\fBe\fP\(+-dd の形に変換する。
 286 小数点の前には一桁の数字があり、小数点以下の桁数は精度で指定された桁数
 287 になる。精度は指定されなかった場合 6 とみなされる。 精度が 0 の場合には、
 288 小数点以下は表示されない。\fBE\fP 変換では、指数を表現するときに (\fBe\fP で
 289 はなく) \fBE\fP が使われる。指数部分は少なくとも 2桁表示される。つまり、
 290 指数の値が 0 の場合には、00 と表示される。
 291 .TP
 292 \fBf\fP, \fBF\fP
 293 \fIdouble\fP 引き数を丸めて [\-]ddd\fB\&.\fPddd の形の10進表現に変換する。 小数点の後の桁数は、精度で指定された値となる。
 294 精度が指定されていない場合には 6 として扱われる。 精度として明示的に 0 が指定されたときには、小数点以下は表示されない。
 295 小数点を表示する際には、小数点の前に少なくとも一桁は数字が表示される。
 296
 297 (SUSv2 では、\fBF\fP は規定されておらず、無限や NaN に関する文字列表現を行ってもよいことになっている。 SUSv3 では \fBF\fP
 298 の規定が追加された。 C99 標準では、\fBf\fP 変換では、無限は "[\-]inf" か "[\-]infinity" と表示し、 NaN
 299 は文字列の先頭に `nan' をつけて表示するように規定されている。 \fBF\fP 変換の場合は "[\-]INF", "[\-]INFINITY",
 300 "NAN*" と表示される。)
 301 .TP
 302 \fBg\fP, \fBG\fP
 303 \fIdouble\fP 引き数を \fBf\fP か \fBe\fP (\fBG\fP 変換の場合は \fBF\fP か \fBE\fP)  の形式に変換する。
 304 精度は表示する桁数を指定する。 精度が指定されない場合は、6桁とみなされる。 精度が 0 の場合は、1桁とみなされる。 変換される値の指数が、 \-4
 305 より小さいか、精度以上の場合に、 \fBe\fP 形式が使用される。 変換された結果の小数部分の末尾の 0 は削除される。小数点が表示されるのは、
 306 小数点以下に数字が少なくとも一つある場合にだけである。
 307 .TP
 308 \fBa\fP, \fBA\fP
 309 (C99 にはあるが SUSv2 にはないが SUSv3 で追加された)
 310 \fBa\fP 変換では、 \fIdouble\fP 引き数を
 311 (abcdef の文字を使って) [\-]\fB0x\fPh\fB\&.\fPhhhh\fBp\fP\(+- 形式の
 312 16 進表記に変換する。
 313 \fBA\fP 変換では、前置文字列 \fB0X\fP, 文字 ABCDEF, 指数文字 \fBP\fP を用いる。
 314 小数点の前には 1 桁の 16 進数が置かれ、小数点の後ろの桁数は 精度で指定
 315 された値となる。デフォルトの精度は、その値が 2 進数で正確に表現できる
 316 場合には、その値を正確に表現できる桁数となる。それ以外の場合は、
 317 \fIdouble\fP 型の値を区別するのに十分な大きさとなる。 小数点の前の数字は、
 318 正規化されていない数の場合はいくつになるか分からない。 正規化された数の
 319 場合は、 0 以外の値になるが、いくつになるかは分からない。
 320 .TP
 321 \fBc\fP
 322 \fBl\fP 修飾子がなければ、 \fIint\fP 引き数を \fIunsigned char\fP に変換して、その結果に対応する文字を出力する。 \fBl\fP
 323 修飾子があれば、 \fIwint_t\fP (ワイド文字) 引き数を、 \fBwcrtomb\fP(3)
 324 関数を初期シフト状態で呼び出してマルチバイト文字列に変換し、 変換されたマルチバイト文字列を出力する。
 325 .TP
 326 \fBs\fP
 327 \fBl\fP 修飾子がない場合、 引き数は \fIconst char\ *\fP 型で文字型の配列へのポインタ (文字列へのポインタ) であることが
 328 期待されている。配列中の文字は、終端の ヌルバイト (\(aq\e0\(aq)  が出てくるまで出力される (終端文字は出力されない)。
 329 精度が指定されていると、指定された字数以上は出力されない。 精度が指定された場合には、終端バイトが存在する必要はない。
 330 精度が指定されていなかったり、精度の値が配列の大きさより大きい場合には、 配列は終端のヌルバイトを含んでいなければならない。
 331
 332 \fBl\fP 修飾子が指定されている場合、 引き数は \fIconst wchar_t\ *\fP 型でワイド文字の配列へのポインタであることが期待されている。
 333 配列中のワイド文字は (1文字毎に \fBwcrtomb\fP(3)  を呼び出して) マルチバイト文字に変換される (最初のワイド文字の変換の前に
 334 \fBwcrtomb\fP()  のシフト状態を初期状態に戻してから変換は行われる)。 マルチバイト文字への変換は、文字列を終端するヌルワイド文字が
 335 出てくるまで行われ、終端ヌルワイド文字も含めて変換される。 結果のマルチバイト文字列は、終端のヌルバイトが出てくるまで 出力される
 336 (終端のヌルバイトは出力されない)。 精度が指定された場合、指定されたバイト数以上には出力されない。
 337 但し、マルチバイト文字の一部分だけが出力されることはない。 精度は「バイト」数を指定するものであり、「ワイド文字」数や
 338 「画面での位置」を指定するものではないことに注意。 精度が指定されていて、さらに出力が配列の末尾に達する前に出力バイト数が
 339 精度の値を超える場合だけは、配列はヌルワイド文字で終端されていなくてもよい。 それ以外の場合は、必ず配列はヌルワイド文字で終端されていなければならない。
 340 .TP
 341 \fBC\fP
 342 (C99, C11 にはないが SUSv2, SUSv3, SUSv4 にはある)  \fBlc\fP と同じ。使ってはならない。
 343 .TP
 344 \fBS\fP
 345 (C99, C11 にはないが SUSv2, SUSv3, SUSv4 にはある)  \fBls\fP と同じ。使ってはならない。
 346 .TP
 347 \fBp\fP
 348 \fIvoid\ *\fP ポインタ引き数を (\fB%#x\fP や \fB%#lx\fP のような) 16 進数で出力する。
 349 .TP
 350 \fBn\fP
 351 これまでに書き込まれた文字数が対応する引き数が指す整数に格納される。 この引き数は \fIint\ *\fP
 352 系でなければならず、そのサイズは指定された整数の長さ修飾子 (省略可能) と一致していなければならない。 引き数の変換は行われない。
 353 変換指定にフラグ、フィールド幅、精度に含まれていた場合の動作は不定である。
 354 .TP
 355 \fBm\fP
 356 (glibc での拡張)  \fIstrerror(errno)\fP の出力を表示する。引き数は必要ない。
 357 .TP
 358 \fB%\fP
 359 \(aq%\(aq 文字を出力する。変換される引き数は無い。 変換指定全体を書くと "%%" となる。
 360 .SH 準拠
 361 \fBfprintf\fP(), \fBprintf\fP(), \fBsprintf\fP(), \fBvprintf\fP(), \fBvfprintf\fP(),
 362 \fBvsprintf\fP()  関数は、C89 と C99 に準拠している。 \fBsnprintf\fP()  と \fBvsnprintf\fP()  は C99
 363 に準拠している。
 364 .PP
 365 .\" .PP
 366 .\" Linux libc4 knows about the five C standard flags.
 367 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
 368 .\" and the conversions
 369 .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
 370 .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
 371 .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
 372 .\" where \fBF\fP is a synonym for \fBf\fP.
 373 .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
 374 .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
 375 .\" (This is bad, and caused serious bugs later, when
 376 .\" support for \fB%D\fP disappeared.)
 377 .\" No locale-dependent radix character,
 378 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
 379 .\" .PP
 380 .\" Linux libc5 knows about the five C standard flags and the \(aq flag,
 381 .\" locale, "%m$" and "*m$".
 382 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
 383 .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
 384 .\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
 385 .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
 386 .\" but adds the conversion character
 387 .\" .BR m ,
 388 .\" which outputs
 389 .\" .IR strerror(errno) .
 390 .\" .PP
 391 .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
 392 \fBsnprintf\fP()  の返り値を見ると、 SUSv2 と C99 標準は互いに矛盾している。 SUSv2 では、 \fBsnprintf\fP()
 393 が \fIsize\fP=0 で呼び出された場合、 1 未満の値を何か返り値とするように規定している。 一方 C99 では、このような場合 \fIstr\fP を
 394 NULL とし、返り値として (通常通り) 出力バッファが十分な大きさが あった場合に出力されるであろう文字数を返す。 SUSv3 やそれ以降では
 395 C99 の \fBsnprintf\fP() の規定にあわせたものとなっている。
 396 .PP
 397 glibc 2.1 では、長さ修飾子 \fBhh\fP, \fBj\fP, \fBt\fP, \fBz\fP と変換文字 \fBa\fP, \fBA\fP が追加された。
 398 .PP
 399 glibc 2.2 では、 C99 で規定された意味での変換文字 \fBF\fP と フラグ文字 \fBI\fP が追加された。
 400 .SH 注意
 401 テキストを \fIbuf\fP に追加するのに、軽率にも次のようなコードを使っているプログラムがある。
 402
 403     sprintf(buf, "%s some further text", buf);
 404
 405 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
 406 しかしながら、標準規格では、 \fBsprintf\fP(), \fBsnprintf\fP(), \fBvsprintf\fP(), \fBvsnprintf\fP()
 407 の呼び出しにおいて、コピー元とコピー先のバッファが重なっていた場合の 結果は不定である、と明記されている。 使用する \fBgcc\fP(1)
 408 のバージョンや指定したコンパイラのオプション次第では、 上記のような呼び出しで、期待した結果が得られ「ない」ことがある。
 409
 410 .\" .SH HISTORY
 411 .\" UNIX V7 defines the three routines
 412 .\" .BR printf (),
 413 .\" .BR fprintf (),
 414 .\" .BR sprintf (),
 415 .\" and has the flag \-, the width or precision *, the length modifier l,
 416 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
 417 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
 418 .\" #, + and <space> and no longer mentions D,O,U,X.
 419 .\" 2.11BSD has
 420 .\" .BR vprintf (),
 421 .\" .BR vfprintf (),
 422 .\" .BR vsprintf (),
 423 .\" and warns not to use D,O,U,X.
 424 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
 425 .\" and the conversions n, p, E, G, X (with current meaning)
 426 .\" and deprecates D,O,U.
 427 .\" 4.4BSD introduces the functions
 428 .\" .BR snprintf ()
 429 .\" and
 430 .\" .BR vsnprintf (),
 431 .\" and the length modifier q.
 432 .\" FreeBSD also has functions
 433 .\" .BR asprintf ()
 434 .\" and
 435 .\" .BR vasprintf (),
 436 .\" that allocate a buffer large enough for
 437 .\" .BR sprintf ().
 438 .\" In glibc there are functions
 439 .\" .BR dprintf ()
 440 .\" and
 441 .\" .BR vdprintf ()
 442 .\" that print to a file descriptor instead of a stream.
 443 glibc の \fBsnprintf\fP()  と \fBvsnprintf\fP()  の実装は、バージョン 2.1 以降は C99 標準に準拠しており、
 444 上記の通りの動作をする。 glibc 2.0.6 までは、出力が切り詰められた場合は \-1 を返す。
 445 .SH バグ
 446 .\" .PP
 447 .\" Linux libc4.[45] does not have a
 448 .\" .BR snprintf (),
 449 .\" but provides a libbsd that contains an
 450 .\" .BR snprintf ()
 451 .\" equivalent to
 452 .\" .BR sprintf (),
 453 .\" that is, one that ignores the
 454 .\" .I size
 455 .\" argument.
 456 .\" Thus, the use of
 457 .\" .BR snprintf ()
 458 .\" with early libc4 leads to serious security problems.
 459 \fBsprintf\fP()  と \fBvsprintf\fP()  は勝手に十分に長い文字列領域があると仮定するので、呼び出し側は
 460 実際の領域からあふれないように注意しなければならない。 しかし、これを保証することが不可能な場合が多い。
 461 生成される文字列の長さはロケール依存であり、予測が難しいことに注意。 代わりに \fBsnprintf\fP()  と \fBvsnprintf\fP()
 462 (または \fBasprintf\fP(3)  と \fBvasprintf\fP(3))  を使うこと。
 463 .PP
 464 .\" .PP
 465 .\" Some floating-point conversions under early libc4
 466 .\" caused memory leaks.
 467 \fBprintf(\fP\fIfoo\fP\fB);\fP のようなコードはしばしばバグを引き起こす。 なぜなら \fIfoo\fP に %
 468 文字が含まれてるかもしれないからである。 \fIfoo\fP が信頼できないユーザー入力から作られている場合には、 その中に \fB%n\fP
 469 が含まれていることがあり、 \fBprintf\fP()  呼び出し時にメモリへの書き込みが起こり、 セキュリティーホールを作ることになるかもしれない。
 470 .SH 例
 471 \fIPi\fP を 5 桁で出力する。
 472 .in +4n
 473 .nf
 474
 475 #include <math.h>
 476 #include <stdio.h>
 477 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
 478 .fi
 479 .in
 480 .PP
 481 日付と時間を "Sunday, July 3, 10:02" の形式で出力する。 (\fIweekday\fP と \fImonth\fP
 482 は文字列へのポインタである)
 483 .in +4n
 484 .nf
 485
 486 #include <stdio.h>
 487 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
 488         weekday, month, day, hour, min);
 489 .fi
 490 .in
 491 .PP
 492 日 \- 月 \- 年 の順序で表示を行う国も多い。 従って、国際版では書式で指定された順番で 引き数を表示できなければならない。
 493 .in +4n
 494 .nf
 495
 496 #include <stdio.h>
 497 fprintf(stdout, format,
 498         weekday, month, day, hour, min);
 499
 500 .fi
 501 .in
 502 \fIformat\fP はロケールに依存しており、引き数の順番を変えることもできる。 \fIformat\fP が
 503 .in +4n
 504 .nf
 505
 506 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
 507
 508 .fi
 509 .in
 510 であれば、 "Sonntag, 3. Juli, 10:02" という結果になる。
 511 .PP
 512 十分に大きな文字列領域を確保して、そこにメッセージを格納するには (glibc 2.0 と glibc 2.1 の両方で正しく動作するコード):
 513 .nf
 514
 515 #include <stdio.h>
 516 #include <stdlib.h>
 517 #include <stdarg.h>
 518
 519 char *
 520 make_message(const char *fmt, ...)
 521 {
 522     int n;
 523     int size = 100;     /* Guess we need no more than 100 bytes */
 524     char *p, *np;
 525     va_list ap;
 526
 527     p = malloc(size);
 528     if (p == NULL)
 529         return NULL;
 530
 531     while (1) {
 532
 533         /* Try to print in the allocated space */
 534
 535         va_start(ap, fmt);
 536         n = vsnprintf(p, size, fmt, ap);
 537         va_end(ap);
 538
 539         /* Check error code */
 540
 541         if (n < 0) {
 542             free(p);
 543             return NULL;
 544         }
 545
 546         /* If that worked, return the string */
 547
 548         if (n < size)
 549             return p;
 550
 551         /* Else try again with more space */
 552
 553         size = n + 1;       /* Precisely what is needed */
 554
 555
 556         np = realloc(p, size);
 557         if (np == NULL) {
 558             free(p);
 559             return NULL;
 560         } else {
 561             p = np;
 562         }
 563     }
 564 }
 565 .fi
 566 .PP
 567 バージョン 2.0.6 より前の glibc で切り詰めが起こった場合、切り詰めは適切に処理されず、エラーとして扱われる。
 568 .SH 関連項目
 569 \fBprintf\fP(1), \fBasprintf\fP(3), \fBdprintf\fP(3), \fBscanf\fP(3), \fBsetlocale\fP(3),
 570 \fBwcrtomb\fP(3), \fBwprintf\fP(3), \fBlocale\fP(5)
 571 .SH この文書について
 572 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.77 の一部
 573 である。プロジェクトの説明とバグ報告に関する情報は
 574 http://www.kernel.org/doc/man\-pages/ に書かれている。