.\" Updated 2013-05-06, Akihiro MOTOKI <amotoki@gmail.com>
.\" Updated 2013-07-22, Akihiro MOTOKI <amotoki@gmail.com>
.\"
-.TH PRINTF 3 2013\-12\-30 GNU "Linux Programmer's Manual"
+.TH PRINTF 3 2014\-07\-08 GNU "Linux Programmer's Manual"
.SH 名前
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf \-
指定された書式に変換して出力を行う
と同時に指定された場合には、 \fB\&0\fP フラグは無視される。 その他の変換では、動作は未定義である。
.TP
\fB\-\fP
-変換値をフィールド境界で左揃えにする (デフォルトは右揃えである)。 \fBn\fP 変換以外では、変換された値は
-左側ではなく右側を空白文字やゼロで埋められる。 \fB\-\fP と \fB\&0\fP の両方が指定された場合には、 \fB\-\fP が優先される。
+変換値をフィールド境界で左揃えにする (デフォルトは右揃えである)。 変換された値は 左側ではなく右側を空白文字やゼロで埋められる。 \fB\-\fP と
+\fB\&0\fP の両方が指定された場合には、 \fB\-\fP が優先される。
.TP
\&\fB' '\fP
(1個の半角スペース) 符号付き変換で生成された正の数字の前に空白 (または空文字列) が置かれる。
符号付き変換によって出力される数字の前に、常に符号 (+ か \-) が置かれる。 デフォルトでは、符号は負の数字の場合のみ付与される。 \fB+\fP
と半角スペースの 両方が使われている場合には、 \fB+\fP が優先される。
.PP
-上記の 5 つのフラグは C 標準で定義されている。 SUSv2 では、さらにもう一つフラグ文字が規定されている。
+上記の 5 つのフラグは C99 標準で定義されている。 Single UNIX Specified では、さらにもう一つフラグ文字が規定されている。
.TP
\fB\(aq\fP
10進数変換 (\fBi\fP, \fBd\fP, \fBu\fP, \fBf\fP, \fBF\fP, \fBg\fP, \fBG\fP) において、ロケール情報に指定があれば 1000
単位の区切り文字を出力する。 \fBgcc\fP(1) の多くのバージョンは、このオプションを解釈することができず、 警告を出力することに注意せよ。
-%\(aqF は SUSv2 には含まれていない。
+(\fI%\(aqF\fP は SUSv2 には含まれていなかったが、 SUSv3 で追加された。
.PP
glibc 2.2 では、さらに一つフラグ文字が追加されている。
.TP
変換に対応する引き数が \fIlong int\fP へのポインタであることを示す。
.TP
\fBL\fP
+.\" .TP
+.\" .B q
+.\" ("quad". 4.4BSD and Linux libc5 only.
+.\" Don't use.)
\fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, \fBg\fP, \fBG\fP 変換に対応する引き数が \fIlong double\fP
-であることを示す。 (C99 では %LF を使うことを認めているが、SUSv2 では認められていない。)
-.TP
-\fBq\fP
-("quad"。 4.4BSD と Linux libc5 のみ有効。使ってはならない。) \fBll\fP と同じ意味である。
+であることを示す。 (C99 では %LF を使うことを認めているが、SUSv2 では認められていない。) これは \fBll\fP の同義語である。
.TP
\fBj\fP
-整数変換に対応する引き数が \fIintmax_t\fP か \fIuintmax_t\fP であることを示す。
+A following integer conversion corresponds to an \fIintmax_t\fP or \fIuintmax_t\fP
+argument, or a following \fBn\fP conversion corresponds to a pointer to an
+\fIintmax_t\fP argument.
.TP
\fBz\fP
-整数変換に対応する引き数が \fIsize_t\fP か \fIssize_t\fP であることを示す。 (Linux libc5 では、これを指定するのに
-\fBZ\fP を用いる。使ってはならない。)
+.\" (Linux libc5 has
+.\" .B Z
+.\" with this meaning.
+.\" Don't use it.)
+A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP
+argument, or a following \fBn\fP conversion corresponds to a pointer to a
+\fIsize_t\fP argument.
.TP
\fBt\fP
-整数変換に対応する引き数が \fIptrdiff_t\fP であることを示す。
+A following integer conversion corresponds to a \fIptrdiff_t\fP argument, or a
+following \fBn\fP conversion corresponds to a pointer to a \fIptrdiff_t\fP
+argument.
.PP
-SUSv2 で長さ修飾子として使用できるのは、 \fBh\fP (\fBhd\fP, \fBhi\fP, \fBho\fP, \fBhx\fP, \fBhX\fP, \fBhn\fP),
-\fBl\fP (\fBld\fP, \fBli\fP, \fBlo\fP, \fBlx\fP, \fBlX\fP, \fBln\fP, \fBlc\fP, \fBls\fP), \fBL\fP (\fBLe\fP,
-\fBLE\fP, \fBLf\fP, \fBLg\fP, \fBLG\fP) だけである。
+SUSv3 では上記のすべてが規定されている。 SUSv2 で規定されていたのは、 長さ修飾子 \fBh\fP (\fBhd\fP, \fBhi\fP, \fBho\fP,
+\fBhx\fP, \fBhX\fP, \fBhn\fP), \fBl\fP (\fBld\fP, \fBli\fP, \fBlo\fP, \fBlx\fP, \fBlX\fP, \fBln\fP, \fBlc\fP,
+\fBls\fP), \fBL\fP (\fBLe\fP, \fBLE\fP, \fBLf\fP, \fBLg\fP, \fBLG\fP) だけであった。
.SS 変換指定子
適用される変換の型を指定する文字。 変換指定子とその意味は以下の通りである。
.TP
精度が指定されていない場合には 6 として扱われる。 精度として明示的に 0 が指定されたときには、小数点以下は表示されない。
小数点を表示する際には、小数点の前に少なくとも一桁は数字が表示される。
-(SUSv2 では、\fBF\fP は規定されておらず、無限や NaN に関する文字列表現を
-行ってもよいことになっている。
- C99 標準では、\fBf\fP 変換では、無限は "[\-]inf" か "[\-]infinity" と表示し、
-NaN は文字列の先頭に `nan' をつけて表示するように規定されている。
-\fBF\fP 変換の場合は "[\-]INF", "[\-]INFINITY", "NAN*" と表示される。)
+(SUSv2 does not know about \fBF\fP and says that character string
+representations for infinity and NaN may be made available. SUSv3 adds a
+specification for \fBF\fP. The C99 standard specifies "[\-]inf" or
+"[\-]infinity" for infinity, and a string starting with "nan" for NaN, in the
+case of \fBf\fP conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN*" in the case
+of \fBF\fP conversion.)
.TP
\fBg\fP, \fBG\fP
\fIdouble\fP 引き数を \fBf\fP か \fBe\fP (\fBG\fP 変換の場合は \fBF\fP か \fBE\fP) の形式に変換する。
小数点以下に数字が少なくとも一つある場合にだけである。
.TP
\fBa\fP, \fBA\fP
-(C99 にはあるが SUSv2 にはない) \fBa\fP 変換では、 \fIdouble\fP 引き数を
-(abcdef の文字を使って) [\-]\fB0x\fPh\fB\&.\fPhhhh\fBp\fP\(+- 形式の
-16 進表記に変換する。
-\fBA\fP 変換では、前置文字列 \fB0X\fP, 文字 ABCDEF, 指数文字 \fBP\fP を用いる。
-小数点の前には 1 桁の 16 進数が置かれ、小数点の後ろの桁数は 精度で指定
-された値となる。デフォルトの精度は、その値が 2 進数で正確に表現できる
-場合には、その値を正確に表現できる桁数となる。それ以外の場合は、
-\fIdouble\fP 型の値を区別するのに十分な大きさとなる。 小数点の前の数字は、
-正規化されていない数の場合はいくつになるか分からない。 正規化された数の
-場合は、 0 以外の値になるが、いくつになるかは分からない。
+(C99; not in SUSv2, but added in SUSv3) For \fBa\fP conversion, the \fIdouble\fP
+argument is converted to hexadecimal notation (using the letters abcdef) in
+the style [\-]\fB0x\fPh\fB\&.\fPhhhh\fBp\fP\(+-; for \fBA\fP conversion the prefix \fB0X\fP,
+the letters ABCDEF, and the exponent separator \fBP\fP 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 \fIdouble\fP.
+The digit before the decimal point is unspecified for nonnormalized numbers,
+and nonzero but otherwise unspecified for normalized numbers.
.TP
\fBc\fP
\fBl\fP 修飾子がなければ、 \fIint\fP 引き数を \fIunsigned char\fP に変換して、その結果に対応する文字を出力する。 \fBl\fP
精度の値を超える場合だけは、配列はヌルワイド文字で終端されていなくてもよい。 それ以外の場合は、必ず配列はヌルワイド文字で終端されていなければならない。
.TP
\fBC\fP
-(C99 にはないが SUSv2 にはある) \fBlc\fP と同じ。使ってはならない。
+(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) Synonym for \fBlc\fP.
+Don't use.
.TP
\fBS\fP
-(C99 にはないが SUSv2 にはある) \fBls\fP と同じ。使ってはならない。
+(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) Synonym for \fBls\fP.
+Don't use.
.TP
\fBp\fP
\fIvoid\ *\fP ポインタ引き数を (\fB%#x\fP や \fB%#lx\fP のような) 16 進数で出力する。
.TP
\fBn\fP
-これまでに出力された文字数を \fIint\ *\fP (または類似の型) のポインタ引き数が指す整数に保存する。 引き数の変換は行われない。
+The number of characters written so far is stored into the integer pointed
+to by the corresponding argument. That argument shall be an \fIint\ * ,\fP or
+variant whose size matches the (optionally) supplied integer length
+modifier. No argument is converted. The behavior is undefined if the
+conversion specification includes any flags, a field width, or a precision.
.TP
\fBm\fP
(glibc での拡張) \fIstrerror(errno)\fP の出力を表示する。引き数は必要ない。
\fBvsprintf\fP() 関数は、C89 と C99 に準拠している。 \fBsnprintf\fP() と \fBvsnprintf\fP() は C99
に準拠している。
.PP
-\fBsnprintf\fP() の返り値を見ると、 SUSv2 と C99 標準は互いに矛盾している。 SUSv2 では、 \fBsnprintf\fP()
-が \fIsize\fP=0 で呼び出された場合、 1 未満の値を何か返り値とするように規定している。 一方 C99 では、このような場合 \fIstr\fP を
-NULL とし、返り値として (通常通り) 出力バッファが十分な大きさが あった場合に出力されるであろう文字数を返す。
-.PP
-Linux libc4 では、 5 つの C 標準のフラグ、 長さ修飾子 \fBh\fP, \fBl\fP, \fBL\fP、変換 \fBc\fP, \fBd\fP, \fBe\fP,
-\fBE\fP, \fBf\fP, \fBF\fP, \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP, \fBs\fP, \fBu\fP, \fBx\fP, \fBX\fP
-が使える。 但し \fBF\fP は \fBf\fP と同義である。 また、 \fBD\fP, \fBO\fP, and \fBU\fP を \fBld\fP, \fBlo\fP, and
-\fBlu\fP と同じものとして使える (これはまずい仕様で、 後に \fB%D\fP の対応が打ち切られた時に深刻なバグを
-引き起こした)。ロケール依存の小数点、1000 区切り、 NaN と無限、 "%m$" と "*m$" は使えない。
-.PP
-Linux libc5 では、 5 つの C 標準のフラグと \(aq フラグ、ロケール、 "%m$" と "*m$" が使える。 また、長さ修飾子
-\fBh\fP, \fBl\fP, \fBL\fP, \fBZ\fP, iand \fBq\fP が使えるが、 \fBL\fP と \fBq\fP は両方とも \fIlong double\fP と
-\fIlong long int\fP に対応している (これはバグである)。 現在では変換 \fBF\fP, \fBD\fP, \fBO\fP, \fBU\fP
-は認識されないが、変換文字 \fBm\fP が追加された。これは \fIstrerror(errno)\fP を出力するものである。
-.PP
-glibc 2.0 では、変換文字 \fBC\fP と \fBS\fP が追加された。
+.\" .PP
+.\" Linux libc4 knows about the five C standard flags.
+.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
+.\" and the conversions
+.\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
+.\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
+.\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
+.\" where \fBF\fP is a synonym for \fBf\fP.
+.\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
+.\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
+.\" (This is bad, and caused serious bugs later, when
+.\" support for \fB%D\fP disappeared.)
+.\" No locale-dependent radix character,
+.\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
+.\" .PP
+.\" Linux libc5 knows about the five C standard flags and the \(aq flag,
+.\" locale, "%m$" and "*m$".
+.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
+.\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
+.\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
+.\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
+.\" but adds the conversion character
+.\" .BR m ,
+.\" which outputs
+.\" .IR strerror(errno) .
+.\" .PP
+.\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
+Concerning the return value of \fBsnprintf\fP(), SUSv2 and C99 contradict each
+other: when \fBsnprintf\fP() is called with \fIsize\fP=0 then SUSv2 stipulates an
+unspecified return value less than 1, while C99 allows \fIstr\fP to be NULL in
+this case, and gives the return value (as always) as the number of
+characters that would have been written in case the output string has been
+large enough. SUSv3 and later align their specification of \fBsnprintf\fP()
+with C99.
.PP
glibc 2.1 では、長さ修飾子 \fBhh\fP, \fBj\fP, \fBt\fP, \fBz\fP と変換文字 \fBa\fP, \fBA\fP が追加された。
.PP
glibc の \fBsnprintf\fP() と \fBvsnprintf\fP() の実装は、バージョン 2.1 以降は C99 標準に準拠しており、
上記の通りの動作をする。 glibc 2.0.6 までは、出力が切り詰められた場合は \-1 を返す。
.SH バグ
+.\" .PP
+.\" Linux libc4.[45] does not have a
+.\" .BR snprintf (),
+.\" but provides a libbsd that contains an
+.\" .BR snprintf ()
+.\" equivalent to
+.\" .BR sprintf (),
+.\" that is, one that ignores the
+.\" .I size
+.\" argument.
+.\" Thus, the use of
+.\" .BR snprintf ()
+.\" with early libc4 leads to serious security problems.
\fBsprintf\fP() と \fBvsprintf\fP() は勝手に十分に長い文字列領域があると仮定するので、呼び出し側は
実際の領域からあふれないように注意しなければならない。 しかし、これを保証することが不可能な場合が多い。
生成される文字列の長さはロケール依存であり、予測が難しいことに注意。 代わりに \fBsnprintf\fP() と \fBvsnprintf\fP()
(または \fBasprintf\fP(3) と \fBvasprintf\fP(3)) を使うこと。
.PP
-Linux libc4.[45] には \fBsnprintf\fP() はないが、 libbsd が提供されており、 その中には \fBsprintf\fP()
-と等価な (つまり \fIsize\fP 引き数を無視する) \fBsnprintf\fP() がある。 したがって、初期の libc4 で
-\fBsnprintf\fP() を使うと、深刻なセキュリティ問題を引き起こすことがある。
-.PP
.\" .PP
.\" Some floating-point conversions under early libc4
.\" caused memory leaks.
\fBprintf\fP(1), \fBasprintf\fP(3), \fBdprintf\fP(3), \fBscanf\fP(3), \fBsetlocale\fP(3),
\fBwcrtomb\fP(3), \fBwprintf\fP(3), \fBlocale\fP(5)
.SH この文書について
-この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.68 の一部
+この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.76 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
