release/man3/printf.3

   1 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .\"
  24 .\" Earlier versions of this page influenced the present text.
  25 .\" It was derived from a Berkeley page with version
  26 .\"       @(#)printf.3    6.14 (Berkeley) 7/30/91
  27 .\" converted for Linux by faith@cs.unc.edu, updated by
  28 .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
  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 .\" Japanese Version Copyright (c) 1997 YOSHINO Takashi all rights reserved.
  35 .\" Translated 1998-02-17, YOSHINO Takashi <yoshino@civil.jcn.nihon-u.ac.jp>
  36 .\" Updated 2000-10-02, Kentaro Shirakata <argrath@ub32.org>
  37 .\" Updated 2001-01-29, Kentaro Shirakata <argrath@ub32.org>
  38 .\" Updated 2002-01-03, Kentaro Shirakata <argrath@ub32.org>
  39 .\" Updated 2002-10-17, Kentaro Shirakata <argrath@ub32.org>
  40 .\" Updated 2005-03-15, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  41 .\" Updated 2006-07-20, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  42 .\" Updated 2008-02-10, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.77
  43 .\" Updated 2009-03-03, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.19
  44 .\"
  45 .\" WORD: conversion specifier  変換指定子
  46 .\" WORD: length modifier       長さ修飾子
  47 .\"
  48 .TH PRINTF 3  2011-09-28 "GNU" "Linux Programmer's Manual"
  49 .SH 名前
  50 printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf,
  51 vsnprintf \- 指定された書式に変換して出力を行う
  52 .SH 書式
  53 .B #include <stdio.h>
  54 .sp
  55 .BI "int printf(const char *" format ", ...);"
  56 .br
  57 .BI "int fprintf(FILE *" stream ", const char *" format ", ...);"
  58 .br
  59 .BI "int sprintf(char *" str ", const char *" format ", ...);"
  60 .br
  61 .BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);"
  62 .sp
  63 .B #include <stdarg.h>
  64 .sp
  65 .BI "int vprintf(const char *" format ", va_list " ap );
  66 .br
  67 .BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap );
  68 .br
  69 .BI "int vsprintf(char *" str ", const char *" format ", va_list " ap );
  70 .br
  71 .BI "int vsnprintf(char *" str ", size_t " size ", const char *" format \
  72 ", va_list " ap );
  73 .sp
  74 .in -4n
  75 glibc 向けの機能検査マクロの要件
  76 .RB ( feature_test_macros (7)
  77 参照):
  78 .in
  79 .sp
  80 .ad l
  81 .BR snprintf (),
  82 .BR vsnprintf ():
  83 .RS 4
  84 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
  85 _POSIX_C_SOURCE\ >=\ 200112L;
  86 .br
  87 or
  88 .I "cc -std=c99"
  89 .RE
  90 .ad
  91 .SH 説明
  92 .BR printf ()
  93 関数グループは、以下で述べるように、
  94 .I format
  95 に従って出力を生成するものである。
  96 .BR printf ()
  97 と
  98 .BR vprintf ()
  99 は出力を
 100 .I stdout
 101 (標準出力ストリーム) に書き出す。
 102 .BR fprintf ()
 103 と
 104 .BR vfprintf ()
 105 は出力を指定された出力
 106 .I stream
 107 に書き出す。
 108 .BR sprintf (),
 109 .BR snprintf (),
 110 .BR vsprintf (),
 111 .BR vsnprintf ()
 112 は出力を文字列
 113 .IR str
 114 に書き込む。
 115 .PP
 116 .BR snprintf ()
 117 と
 118 .BR vsnprintf ()
 119 は最大で
 120 .I size
 121 バイトを
 122 .I str
 123 に書き込む
 124 .RI ( size
 125 には文字列を終端する NULL バイト (\(aq\e0\(aq) もを含まれる)。
 126 .PP
 127 .BR vprintf (),
 128 .BR vfprintf (),
 129 .BR vsprintf (),
 130 .BR vsnprintf ()
 131 の各関数はそれぞれ
 132 .BR printf (),
 133 .BR fprintf (),
 134 .BR sprintf (),
 135 .BR snprintf (),
 136 の各関数と等価であり、可変数引き数の代わりに
 137 .I va_list
 138 を引き数として呼び出される点だけが異なる。
 139 これらの関数では
 140 .I va_end
 141 マクロは呼び出されない。
 142 これらの関数は
 143 .I va_arg
 144 を呼び出すので、呼び出し後の
 145 .I ap
 146 の値は未定義である。
 147 .BR stdarg (3)
 148 を参照のこと。
 149 .PP
 150 これらの 8 つの関数は
 151 .I format
 152 文字列の制御に従って出力を書き出す。
 153 .I format
 154 文字列は、これに続く引き数 (または
 155 .BR stdarg (3)
 156 の可変長引き数機構を使ってアクセスできる引き数)
 157 をどのように変換して出力するかを指定する。
 158
 159 C99 と POSIX.1-2001 では、
 160 .BR sprintf (),
 161 .BR snprintf (),
 162 .BR vsprintf (),
 163 .BR vsnprintf ()
 164 の呼び出しで、範囲が重複するオブジェクト間でコピーが発生する場合の
 165 結果は不定であると規定されている (例えば、出力先の文字列と入力された
 166 引き数の一つが同じバッファを参照している場合などである)。
 167 「注意」の節を参照。
 168 .SS 返り値
 169 成功時には、上記の関数は書き込まれた文字数を返す
 170 (文字列の最後を示すために使用する NULL バイトは数に含まれない)。
 171
 172 .BR snprintf ()
 173 と
 174 .BR vsnprintf ()
 175 は、
 176 .I size
 177 バイトを越える文字数を書き込まない
 178 .RI ( size
 179 には文字列を終端する NULL バイト (\(aq\e0\(aq) も含まれる)。
 180 この制限によって出力が切り詰められた場合には、
 181 もし十分なスペースがあれば書き込まれたであろう文字の個数
 182 (文字列を終端する NULL バイトを除く) を返す。
 183 従って、返り値が
 184 .I size
 185 以上だった場合、出力が切り詰められたことを意味する
 186 (後述の注意も参照のこと)。
 187
 188 エラーが発生した場合は、負の数を返す。
 189 .SS フォーマット文字列のフォーマット
 190 フォーマット文字列は文字の列で、
 191 (もしあるなら) 初期シフト状態で始まり、初期シフト状態で終わる。
 192 フォーマット用の文字列は 0 個以上の命令 (directives) によって構成される。
 193 命令には、通常文字と変換指定 (conversion specifications) がある。
 194 通常文字は
 195 .B %
 196 以外の文字で、出力ストリームにそのままコピーされる。
 197 変換指定は、それぞれが 0 個以上の引き数を取る。
 198 各変換指定は文字
 199 .B %
 200 で始まり、
 201 .I "変換指定子 (conversion specifier)"
 202 で終わる。
 203 .B %
 204 と変換指定子の間には、0 個以上の
 205 .I フラグ 、
 206 最小
 207 .I フィールド幅 、
 208 .I 精度 、
 209 .I 長さ修飾子
 210 を (この順序で) 置くことができる。
 211
 212 引き数は (型の格上げの後は) 変換指定子が表す型と正確に対応しなければならない。
 213 デフォルトでは、\(aq*\(aq や変換指定子が出てくる毎に次の引き数を要求され、
 214 引き数は指定された順序で使用されていく
 215 (指定された引き数の個数が不十分ならエラーとなる)。
 216 また、引き数が必要な箇所で \(aq%\(aq の代わりに "%m$"、
 217 \(aq*\(aqの代わりに "*m$" と書くことで、
 218 明示的にどの引き数を使用するかを指定することもできる。
 219 ここで 10進の整数 m は希望の引き数の引き数リストでの位置を示す
 220 (最初の引き数の番号が 1 である)。
 221 従って、以下の二つは等価である。
 222 .in +4n
 223 .nf
 224
 225 printf("%*d", width, num);
 226
 227 printf("%2$*1$d", width, num);
 228
 229 .fi
 230 .in
 231 は等価である。
 232 二番目の書き方では同じ引き数を繰り返し参照することができる。
 233 C99 標準には、 Single UNIX Specification 由来の \(aq$\(aq を使った書き方は含まれていない。
 234 \(aq$\(aq を使ったスタイルを使うと、引き数を取る変換及び幅と精度の引き数を
 235 全てこのスタイルで指定しなければならないが、
 236 引き数を消費しない "%%" フォーマットと混ざっているかもしれない。
 237 \(aq$\(aq で指定される引き数の番号に空きがあってはならない。
 238 例えば、もし引き数 1 と 3 が指定されると、引き数 2 もフォーマット文字列のどこかで
 239 指定されなければならない。
 240
 241 数値変換には小数点や 1000 単位の区切り文字を使うものもある。
 242 実際にどの文字を使うかはロケールの
 243 .B LC_NUMERIC
 244 による。
 245 POSIX ロケールでは小数点に \(aq.\(aq を用い、
 246 区切り文字は使わない。
 247 従って、
 248 .in +4n
 249 .nf
 250
 251 printf("%\(aq.2f", 1234567.89);
 252
 253 .fi
 254 .in
 255 は、 POSIX ロケールでは "1234567.89" 、 nl_NL ロケールでは "1234567,89"、
 256 da_DK ロケールでは "1.234.567,89" となる。
 257 .SS フラグ文字
 258 % 文字の後ろには 0 個以上のフラグ文字が続く。
 259 .TP
 260 .B #
 261 値は「別の形式」に変換される。
 262 .B o
 263 変換の場合、(先頭文字が 0 になっていない場合に先頭に 0 を追加することで)
 264 出力文字列の最初の文字を 0 にする。
 265 .B x
 266 と
 267 .B X
 268 変換の場合、数値が 0 でないときには文字列 "0x"
 269 .RB ( X
 270 変換の場合には "0X") が前に付与される。
 271 .BR a ,
 272 .BR A ,
 273 .BR e ,
 274 .BR E ,
 275 .BR f ,
 276 .BR F ,
 277 .BR g ,
 278 .B G
 279 変換では、 小数点に続く数字がなくても、
 280 出力には常に小数点が含まれる
 281 (通常は、小数点の後に数字が続く場合にのみ、
 282 小数点が表示される)。
 283 .B g
 284 と
 285 .B G
 286 変換の場合、他の変換とは異なり、末尾のゼロが変換結果から削除されない。
 287 その他の変換では、結果は未定義である。
 288 .TP
 289 .B \&0
 290 値をゼロで埋める。
 291 .BR d ,
 292 .BR i ,
 293 .BR o ,
 294 .BR u ,
 295 .BR x ,
 296 .BR X ,
 297 .BR a ,
 298 .BR A ,
 299 .BR e ,
 300 .BR E ,
 301 .BR f ,
 302 .BR F ,
 303 .BR g ,
 304 .B G
 305 変換では、変換した値の左側を空白文字の代わりにゼロで埋める。
 306 .B \&0
 307 と
 308 .B \-
 309 が両方とも指定された場合は、
 310 .B \&0
 311 フラグは無視される。
 312 精度が数値変換
 313 .RB ( d ,
 314 .BR i ,
 315 .BR o ,
 316 .BR u ,
 317 .BR x ,
 318 .BR X )
 319 と同時に指定された場合には、
 320 .B \&0
 321 フラグは無視される。
 322 その他の変換では、動作は未定義である。
 323 .TP
 324 .B \-
 325 変換値をフィールド境界で左揃えにする
 326 (デフォルトは右揃えである)。
 327 .B n
 328 変換以外では、変換された値は
 329 左側ではなく右側を空白文字やゼロで埋められる。
 330 .B \-
 331 と
 332 .B \&0
 333 の両方が指定された場合には、
 334 .B \-
 335 が優先される。
 336 .TP
 337 .B ' '
 338 (1個の半角スペース)
 339 符号付き変換で生成された正の数字の前に空白 (または空文字列) が置かれる。
 340 .TP
 341 .B +
 342 符号付き変換によって出力される数字の前に、常に符号 (+ か \-) が置かれる。
 343 デフォルトでは、符号は負の数字の場合のみ付与される。
 344 .B +
 345 と半角スペースの
 346 両方が使われている場合には、
 347 .B +
 348 が優先される。
 349 .PP
 350 上記の 5 つのフラグは C 標準で定義されている。
 351 SUSv2 では、さらにもう一つフラグ文字が規定されている。
 352 .TP
 353 .B \(aq
 354 10進数変換
 355 .RB ( i ,
 356 .BR d ,
 357 .BR u ,
 358 .BR f ,
 359 .BR F ,
 360 .BR g ,
 361 .BR G )
 362 において、ロケール情報に指定があれば 1000 単位の区切り文字を出力する。
 363 .BR gcc (1)
 364 の多くのバージョンは、このオプションを解釈することができず、
 365 警告を出力することに注意せよ。
 366 %\(aqF は SUSv2 には含まれていない。
 367 .PP
 368 glibc 2.2 では、さらに一つフラグ文字が追加されている。
 369 .TP
 370 .B I
 371 10進整数変換
 372 .RB ( i ,
 373 .BR d ,
 374 .BR u )
 375 において、ロケールの代替出力数字があれば、それを用いて出力する。
 376 例えば、 glibc 2.2.3 以降では、ペルシア ("fa_IR") ロケールで
 377 アラビア数字 (Arabic-Indic digits) を出力できる。
 378 .\" ロケールファイルには outdigits というキーワードがある。
 379 .SS フィールド幅
 380 最小のフィールド幅を指定する 10進数の数値文字列 (文字列の最初の文字は
 381 ゼロ以外)。本項目はオプションである。
 382 変換された値の文字数がフィールド長よりも少ない場合、
 383 フィールドの左側をスペースで埋める
 384 (左揃えのフラグがある場合は右側を埋める)。
 385 10進数の文字列の代わりに "*" や "*m$" (\fIm\fP は 10進整数) を書くこともできる。
 386 "*" と "*m$" はそれぞれ、次の引き数と \fIm\fP 番目の引き数をフィールド幅として
 387 使うことを指定する (これらの引き数は
 388 .I int
 389 型でなければならない)。
 390 フィールド幅に負の数が指定された場合は、
 391 \(aq\-\(aq フラグと正の数のフィールド幅として扱われる。
 392 フィールド幅が小さかったり指定がなかったりしても、フィールドが切り詰められる
 393 ことはない。もし変換結果がフィールド幅よりも広かった場合、
 394 フィールドは変換結果が入る幅に広げられる。
 395 .SS 精度
 396 オプションである精度は、ピリオド (\(aq.\(aq) とそれに続く10進数という
 397 形式で指定する (10進数はオプション) 。
 398 10進数の文字列の代わりに "*" や "*m$" (m は 10 進整数)を書くこともできる。
 399 "*" と "*m$" はそれぞれ、次の引き数と m 番目の引き数を精度として
 400 使うことを指定する (これらの引き数は
 401 .I int
 402 型でなければならない)。
 403 精度として \(aq.\(aq だけが指定されたり、精度が負の数だった場合、
 404 精度はゼロとみなされる。
 405 .BR d ,
 406 .BR i ,
 407 .BR o ,
 408 .BR u ,
 409 .BR x ,
 410 .B X
 411 変換では、表示される最小の桁数を指定する。
 412 .BR a ,
 413 .BR A ,
 414 .BR e ,
 415 .BR E ,
 416 .BR f ,
 417 .B F
 418 変換では、小数点以下に表示される数字の桁数を指定する。
 419 .B g
 420 と
 421 .B G
 422 変換では、有効数字の最大桁数を指定する。
 423 .B s
 424 と
 425 .B S
 426 変換では、文字列から出力される最大文字数を指定する。
 427 .SS 長さ修飾子
 428 「整数変換」とは、
 429 .BR d ,
 430 .BR i ,
 431 .BR o ,
 432 .BR u ,
 433 .BR x ,
 434 .B X
 435 変換のことである。
 436 .TP
 437 .B hh
 438 整数変換に対応する引き数が
 439 .I signed char
 440 か
 441 .I unsigned char
 442 で、
 443 .B n
 444 変換に対応する引き数が
 445 .I signed char
 446 へのポインタであることを示す。
 447 .TP
 448 .B h
 449 整数変換に対応する引き数が
 450 .I short int
 451 か
 452 .I unsigned short int
 453 で、
 454 .B n
 455 変換に対応する引き数が
 456 .I short int
 457 へのポインタであることを示す。
 458 .TP
 459 .BR l " (エル)"
 460 各変換に対応する引き数が、
 461 整数変換では
 462 .IR "long int" か
 463 .IR "unsigned long int" 、
 464 .B n
 465 変換では
 466 .I long long int
 467 へのポインタ、
 468 .B c
 469 変換では
 470 .IR wint_t 、
 471 .B s
 472 変換では
 473 .I wchar_t
 474 へのポインタであることを示す。
 475
 476 .TP
 477 .BR ll " (エルエル)"
 478 整数変換に対応する引き数が
 479 .I long long int
 480 か
 481 .I unsigned long long int
 482 で、
 483 .B n
 484 変換に対応する引き数が
 485 .I long int
 486 へのポインタであることを示す。
 487 .TP
 488 .B L
 489 .BR a ,
 490 .BR A ,
 491 .BR e ,
 492 .BR E ,
 493 .BR f ,
 494 .BR F ,
 495 .BR g ,
 496 .B G
 497 変換に対応する引き数が
 498 .I long double
 499 であることを示す。
 500 (C99 では %LF を使うことを認めているが、SUSv2 では認められていない。)
 501 .TP
 502 .B q
 503 ("quad"。 4.4BSD と Linux libc5 のみ有効。使ってはならない。)
 504 .B ll
 505 と同じ意味である。
 506 .TP
 507 .B j
 508 整数変換に対応する引き数が
 509 .I intmax_t
 510 か
 511 .I uintmax_t
 512 であることを示す。
 513 .TP
 514 .B z
 515 整数変換に対応する引き数が
 516 .I size_t
 517 か
 518 .I ssize_t
 519 であることを示す。
 520 (Linux libc5 では、これを指定するのに
 521 .B Z
 522 を用いる。使ってはならない。)
 523 .TP
 524 .B t
 525 整数変換に対応する引き数が
 526 .I ptrdiff_t
 527 であることを示す。
 528 .PP
 529 SUSv2 で長さ修飾子として使用できるのは、
 530 .B h
 531 .RB ( hd ,
 532 .BR hi ,
 533 .BR ho ,
 534 .BR hx ,
 535 .BR hX ,
 536 .BR hn ),
 537 .B l
 538 .RB ( ld ,
 539 .BR li ,
 540 .BR lo ,
 541 .BR lx ,
 542 .BR lX ,
 543 .BR ln ,
 544 .BR lc ,
 545 .BR ls ),
 546 .B L
 547 .RB ( Le ,
 548 .BR LE ,
 549 .BR Lf ,
 550 .BR Lg ,
 551 .BR LG )
 552 だけである。
 553 .SS 変換指定子
 554 適用される変換の型を指定する文字。
 555 .PP
 556 変換指定子とその意味は以下の通りである。
 557 .TP
 558 .BR d ", " i
 559 .I int
 560 引き数を符号付き 10 進表記に変換する。
 561 精度指定があれば、精度で指定した桁数は必ず出力される。変換後の値が
 562 指定された桁数に足りない場合は、左側が 0 で埋められる。
 563 デフォルトの精度は 1 である。
 564 0 を表示しようとした時に、明示的に精度として 0 が指定されていると、
 565 出力は空文字列となる。
 566 .TP
 567 .BR o ", " u ", " x ", " X
 568 .I "unsigned int"
 569 引き数を、
 570 符号なし8進数
 571 .RB ( o ),
 572 符号なし10進数
 573 .RB ( u ),
 574 符号なし16進数
 575 .RB ( x
 576 と
 577 .BR X )
 578 に変換する。
 579 .B x
 580 変換では
 581 .B abcdef
 582 が使用され、
 583 .B X
 584 変換では
 585 .B ABCDEF
 586 が使用される。
 587 精度指定があれば、精度で指定した桁数は必ず出力される。変換後の値が
 588 指定された桁数に足りない場合は、左側が 0 で埋められる。
 589 .TP
 590 .BR e ", " E
 591 .I double
 592 引き数を丸めて
 593 .if \w'\*(Pm'=0 .ds Pm \(+-
 594 .RB [\-]d \&. ddd e \\*(Pmdd
 595 の形に変換する。
 596 小数点の前には一桁の数字があり、小数点以下の桁数は精度で指定された
 597 桁数になる。精度は指定されなかった場合 6 とみなされる。
 598 精度が 0 の場合には、小数点以下は表示されない。
 599 .B E
 600 変換では、指数を表現するときに
 601 .RB ( e
 602 ではなく)
 603 .B E
 604 が使われる。
 605 指数部分は少なくとも 2桁表示される。
 606 つまり、指数の値が 0 の場合には、00 と表示される。
 607 .TP
 608 .BR f ", " F
 609 .I double
 610 引き数を丸めて
 611 .RB [\-]ddd \&. ddd
 612 の形の10進表現に変換する。
 613 小数点の後の桁数は、精度で指定された値となる。
 614 精度が指定されていない場合には 6 として扱われる。
 615 精度として明示的に 0 が指定されたときには、小数点以下は表示されない。
 616 小数点を表示する際には、小数点の前に少なくとも一桁は数字が表示される。
 617
 618 (SUSv2 では、
 619 .B F
 620 は規定されておらず、無限や NaN に関する文字列表現を
 621 行ってもよいことになっている。
 622  C99 標準では、
 623 .B f
 624 変換では、無限は "[\-]inf" か "[\-]infinity" と表示し、
 625 NaN は文字列の先頭に `nan' をつけて表示するように規定されている。
 626 .B F
 627 変換の場合は "[\-]INF", "[\-]INFINITY", "NAN*" と表示される。)
 628 .TP
 629 .BR g ", " G
 630 .I double
 631 引き数を
 632 .B f
 633 か
 634 .B e
 635 .RB ( G
 636 変換の場合は
 637 .B F
 638 か
 639 .BR E )
 640 の形式に変換する。
 641 精度は表示する桁数を指定する。
 642 精度が指定されない場合は、6桁とみなされる。
 643 精度が 0 の場合は、1桁とみなされる。
 644 変換される値の指数が、 \-4 より小さいか、精度以上の場合に、
 645 .B e
 646 形式が使用される。
 647 変換された結果の小数部分の末尾の 0 は削除される。小数点が表示されるのは、
 648 小数点以下に数字が少なくとも一つある場合にだけである。
 649 .TP
 650 .BR a ", " A
 651 (C99 にはあるが SUSv2 にはない)
 652 .B a
 653 変換では、
 654 .I double
 655 引き数を (abcdef の文字を使って)
 656 .RB [\-] 0x h \&. hhhh p \\*(Pmd;
 657 形式の 16 進表記に変換する。
 658 .B A
 659 変換では、前置文字列
 660 .BR 0X ,
 661 文字 ABCDEF, 指数文字
 662 .B P
 663 を用いる。
 664 小数点の前には 1桁の16進数が置かれ、小数点の後ろの桁数は
 665 精度で指定された値となる。
 666 デフォルトの精度は、その値が 2進数で正確に表現できる場合には、
 667 その値を正確に表現できる桁数となる。それ以外の場合は、
 668 .I double
 669 型の値を区別するのに十分な大きさとなる。
 670 .\" motoki 2005/03/19: 合っているかな？
 671 小数点の前の数字は、正規化されていない数の場合はいくつになるか分からない。
 672 正規化された数の場合は、 0 以外の値になるが、いくつになるかは分からない。
 673 .TP
 674 .B c
 675 .B l
 676 修飾子がなければ、
 677 .I int
 678 引き数を
 679 .IR "unsigned char"
 680 に変換して、その結果に対応する文字を出力する。
 681 .B l
 682 修飾子があれば、
 683 .I wint_t
 684 (ワイド文字) 引き数を、
 685 .BR wcrtomb (3)
 686 関数を初期シフト状態で呼び出してマルチバイト文字列に変換し、
 687 変換されたマルチバイト文字列を出力する。
 688 .TP
 689 .B s
 690 .B l
 691 修飾子がない場合、
 692 引き数は
 693 .I "const char *"
 694 型で文字型の配列へのポインタ (文字列へのポインタ) であることが
 695 期待されている。配列中の文字は、終端の NULL バイト (\(aq\\0\(aq)
 696 が出てくるまで出力される (終端文字は出力されない)。
 697 精度が指定されていると、指定された字数以上は出力されない。
 698 精度が指定された場合には、終端バイトが存在する必要はない。
 699 精度が指定されていなかったり、精度の値が配列の大きさより大きい場合には、
 700 配列は終端の NULL バイトを含んでいなければならない。
 701
 702 .B l
 703 修飾子が指定されている場合、
 704 引き数は
 705 .I "const wchar_t *"
 706 型でワイド文字の配列へのポインタであることが期待されている。
 707 配列中のワイド文字は (1文字毎に
 708 .BR wcrtomb (3)
 709 を呼び出して) マルチバイト文字に変換される
 710 (最初のワイド文字の変換の前に
 711 .BR wcrtomb ()
 712 のシフト状態を初期状態に戻してから変換は行われる)。
 713 マルチバイト文字への変換は、文字列を終端する NULL ワイド文字が
 714 出てくるまで行われ、終端 NULL ワイド文字も含めて変換される。
 715 結果のマルチバイト文字列は、終端の NULL バイトが出てくるまで
 716 出力される (終端の NULL バイトは出力されない)。
 717 精度が指定された場合、指定されたバイト数以上には出力されない。
 718 但し、マルチバイト文字の一部分だけが出力されることはない。
 719 精度は「バイト」数を指定するものであり、「ワイド文字」数や
 720 「画面での位置」を指定するものではないことに注意。
 721 精度が指定されていて、さらに出力が配列の末尾に達する前に出力バイト数が
 722 精度の値を超える場合だけは、配列は NULL ワイド文字で終端されていなくてもよい。
 723 それ以外の場合は、必ず配列は NULL ワイド文字で終端されていなければならない。
 724 .TP
 725 .B C
 726 (C99 にはないが SUSv2 にはある)
 727 .B lc
 728 と同じ。使ってはならない。
 729 .TP
 730 .B S
 731 (C99 にはないが SUSv2 にはある)
 732 .B ls
 733 と同じ。使ってはならない。
 734 .TP
 735 .B p
 736 .I "void *"
 737 ポインタ引き数を
 738 .RB ( %#x
 739 や
 740 .BR  %#lx
 741 のような) 16 進数で出力する。
 742 .TP
 743 .B n
 744 これまでに出力された文字数を
 745 .I "int *"
 746 (または類似の型) のポインタ引き数が指す整数に保存する。
 747 引き数の変換は行われない。
 748 .TP
 749 .B m
 750 (glibc での拡張)
 751 .I strerror(errno)
 752 の出力を表示する。引き数は必要ない。
 753 .TP
 754 .B %
 755 \(aq%\(aq 文字を出力する。変換される引き数は無い。
 756 変換指定全体を書くと "%%" となる。
 757 .SH 準拠
 758 .BR fprintf (),
 759 .BR printf (),
 760 .BR sprintf (),
 761 .BR vprintf (),
 762 .BR vfprintf (),
 763 .BR vsprintf ()
 764 関数は、C89 と C99 に準拠している。
 765 .BR snprintf ()
 766 と
 767 .BR vsnprintf ()
 768 は C99 に準拠している。
 769 .PP
 770 .BR snprintf ()
 771 の返り値を見ると、
 772 SUSv2 と C99 標準は互いに矛盾している。
 773 SUSv2 では、
 774 .BR snprintf ()
 775 が
 776 .IR size =0
 777 で呼び出された場合、 1 未満の値を何か返り値とするように規定している。
 778 一方 C99 では、このような場合
 779 .I str
 780 を NULL とし、返り値として (通常通り) 出力バッファが十分な大きさが
 781 あった場合に出力されるであろう文字数を返す。
 782 .PP
 783 Linux libc4 では、 5 つの C 標準のフラグ、
 784 長さ修飾子 \fBh\fP, \fBl\fP, \fBL\fP、変換
 785 \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
 786 \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
 787 \fBs\fP, \fBu\fP, \fBx\fP, \fBX\fP
 788 が使える。
 789 但し \fBF\fP は \fBf\fP と同義である。
 790 また、 \fBD\fP, \fBO\fP, and \fBU\fP を \fBld\fP, \fBlo\fP, and \fBlu\fP
 791 と同じものとして使える
 792 (これはまずい仕様で、 後に \fB%D\fP の対応が打ち切られた時に深刻なバグを
 793 引き起こした)。ロケール依存の小数点、1000 区切り、 NaN と無限、
 794 "%m$" と "*m$" は使えない。
 795 .PP
 796 Linux libc5 では、 5 つの C 標準のフラグと \(aq フラグ、ロケール、
 797 "%m$" と "*m$" が使える。
 798 また、長さ修飾子 \fBh\fP, \fBl\fP, \fBL\fP, \fBZ\fP, iand \fBq\fP が使えるが、
 799 \fBL\fP と \fBq\fP は両方とも
 800 \fIlong double\fP と \fIlong long int\fP に対応している (これはバグである)。
 801 現在では変換 \fBF\fP, \fBD\fP, \fBO\fP, \fBU\fP は認識されないが、変換文字
 802 .B m
 803 が追加された。これは
 804 .I strerror(errno)
 805 を出力するものである。
 806 .PP
 807 glibc 2.0 では、変換文字 \fBC\fP と \fBS\fP が追加された。
 808 .PP
 809 glibc 2.1 では、長さ修飾子 \fBhh\fP, \fBj\fP, \fBt\fP, \fBz\fP
 810 と変換文字 \fBa\fP, \fBA\fP が追加された。
 811 .PP
 812 glibc 2.2 では、 C99 で規定された意味での変換文字 \fBF\fP と
 813 フラグ文字 \fBI\fP が追加された。
 814 .SH 注意
 815 テキストを
 816 .I buf
 817 に追加するのに、軽率にも次のようなコードを使っているプログラムがある。
 818
 819     sprintf(buf, "%s some further text", buf);
 820
 821 しかしながら、標準規格では、
 822 .BR sprintf (),
 823 .BR snprintf (),
 824 .BR vsprintf (),
 825 .BR vsnprintf ()
 826 の呼び出しにおいて、コピー元とコピー先のバッファが重なっていた場合の
 827 結果は不定である、と明記されている。
 828 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
 829 使用する
 830 .BR gcc (1)
 831 のバージョンや指定したコンパイラのオプション次第では、
 832 上記のような呼び出しで、期待した結果が得られ「ない」ことがある。
 833
 834 glibc の
 835 .BR snprintf ()
 836 と
 837 .BR vsnprintf ()
 838 の実装は、バージョン 2.1 以降は C99 標準に準拠しており、
 839 上記の通りの動作をする。
 840 glibc 2.0.6 までは、出力が切り詰められた場合は \-1 を返す。
 841 .\" .SH 歴史
 842 .\" UNIX V7 では
 843 .\" .BR printf (),
 844 .\" .BR fprintf (),
 845 .\" .BR sprintf ()
 846 .\" の 3 つの関数と、フラグ \-、幅と精度での *、長さ修飾子 l、
 847 .\" 変換 doxfegcsu、そして ld,ld,lu,lx の同義語として D,O,U,X が定義されている。
 848 .\" 2.9.1BSD でもこれは同じだったが、 2.10BSD では
 849 .\" フラグ #, +, 空白が追加され、 D,O,U,X については記載されなくなった。
 850 .\" 2.11BSD では
 851 .\" .BR vprintf (),
 852 .\" .BR vfprintf (),
 853 .\" .BR vsprintf ()
 854 .\" が追加され、 D,O,U,X を使わないように警告された。
 855 .\" 4.3BSD Reno ではフラグ 0、長さ修飾子 h と L、
 856 .\" 変換 n, p, E, G, (現在の意味での) X が追加され、
 857 .\" D,O,U は非推奨扱いとなった。
 858 .\" 4.4BSD では、関数
 859 .\" .BR snprintf ()と
 860 .\" .BR vsnprintf ()、
 861 .\" 長さ修飾子 q が導入された。
 862 .\" FreeBSD では、
 863 .\" .BR sprintf ()
 864 .\" のために十分なバッファを確保する
 865 .\" .BR asprintf ()
 866 .\" と
 867 .\" .BR vasprintf ()
 868 .\" が追加されている。
 869 .\" glibc には、関数
 870 .\" .BR dprintf (),
 871 .\" .BR vdprintf ()
 872 .\" があり、これらはストリームではなくファイルディスクリプタに出力する。
 873 .SH バグ
 874 .BR sprintf ()
 875 と
 876 .BR vsprintf ()
 877 は勝手に十分に長い文字列領域があると仮定するので、呼び出し側は
 878 実際の領域からあふれないように注意しなければならない。
 879 しかし、これを保証することが不可能な場合が多い。
 880 生成される文字列の長さはロケール依存であり、予測が難しいことに注意。
 881 代わりに
 882 .BR snprintf ()
 883 と
 884 .BR vsnprintf ()
 885 (または
 886 .BR asprintf (3)
 887 と
 888 .BR vasprintf (3))
 889 を使うこと。
 890 .PP
 891 Linux libc4.[45] には
 892 .BR snprintf ()
 893 はないが、 libbsd が提供されており、
 894 その中には
 895 .BR sprintf ()
 896 と等価な (つまり
 897 .I size
 898 引き数を無視する)
 899 .BR snprintf ()
 900 がある。
 901 したがって、初期の libc4 で
 902 .BR snprintf ()
 903 を使うと、深刻なセキュリティ問題を引き起こすことがある。
 904 .PP
 905 .BI printf( foo );
 906 のようなコードはしばしばバグを引き起こす。
 907 なぜなら
 908 .I foo
 909 に % 文字が含まれてるかもしれないからである。
 910 .I foo
 911 が信頼できないユーザー入力から作られている場合には、
 912 その中に \fB%n\fP が含まれていることがあり、
 913 .BR printf ()
 914 呼び出し時にメモリへの書き込みが起こり、
 915 セキュリティーホールを作ることになるかもしれない。
 916 .\".PP
 917 .\".\"O Some floating-point conversions under early libc4
 918 .\".\"O caused memory leaks.
 919 .\"初期の libc4 での実数変換にはメモリリークを引き起こすことがある。
 920 .SH 例
 921 .if \w'\*(Pi'=0 .ds Pi pi
 922 \*(Pi を 5 桁で出力する。
 923 .in +4n
 924 .nf
 925
 926 #include <math.h>
 927 #include <stdio.h>
 928 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
 929 .fi
 930 .in
 931 .PP
 932 日付と時間を "Sunday, July 3, 10:02" の形式で出力する。
 933 .RI ( weekday
 934 と
 935 .I month
 936 は文字列へのポインタである)
 937 .in +4n
 938 .nf
 939
 940 #include <stdio.h>
 941 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
 942         weekday, month, day, hour, min);
 943 .fi
 944 .in
 945 .PP
 946 日 - 月 - 年 の順序で表示を行う国も多い。
 947 従って、国際版では書式で指定された順番で
 948 引き数を表示できなければならない。
 949 .in +4n
 950 .nf
 951
 952 #include <stdio.h>
 953 fprintf(stdout, format,
 954         weekday, month, day, hour, min);
 955
 956 .fi
 957 .in
 958 .I format
 959 はロケールに依存しており、引き数の順番を変えることもできる。
 960 .I format
 961 が
 962 .in +4n
 963 .nf
 964
 965 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
 966
 967 .fi
 968 .in
 969 であれば、 "Sonntag, 3. Juli, 10:02" という結果になる。
 970 .PP
 971 十分に大きな文字列領域を確保して、そこにメッセージを格納するには
 972 (glibc 2.0 と glibc 2.1 の両方で正しく動作するコード):
 973 .nf
 974
 975 #include <stdio.h>
 976 #include <stdlib.h>
 977 #include <stdarg.h>
 978 char *
 979 make_message(const char *fmt, ...)
 980 {
 981     int n;
 982     int size = 100;     /* Guess we need no more than 100 bytes. */
 983     char *p, *np;
 984     va_list ap;
 985
 986     if ((p = malloc(size)) == NULL)
 987         return NULL;
 988
 989     while (1) {
 990
 991         /* Try to print in the allocated space. */
 992
 993         va_start(ap, fmt);
 994         n = vsnprintf(p, size, fmt, ap);
 995         va_end(ap);
 996
 997         /* If that worked, return the string. */
 998
 999         if (n > \-1 && n < size)
1000             return p;
1001
1002         /* Else try again with more space. */
1003
1004         if (n > \-1)    /* glibc 2.1 */
1005             size = n+1; /* precisely what is needed */
1006         else           /* glibc 2.0 */
1007             size *= 2;  /* twice the old size */
1008
1009         if ((np = realloc (p, size)) == NULL) {
1010             free(p);
1011             return NULL;
1012         } else {
1013             p = np;
1014         }
1015     }
1016 }
1017 .fi
1018 .SH 関連項目
1019 .BR printf (1),
1020 .BR asprintf (3),
1021 .BR dprintf (3),
1022 .BR scanf (3),
1023 .BR setlocale (3),
1024 .BR wcrtomb (3),
1025 .BR wprintf (3),
1026 .BR locale (5)