| PRINTF(3) | Linux Programmer's Manual | PRINTF(3) |
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);
snprintf(), vsnprintf():
dprintf(), vdprintf():
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 個以上のフラグ文字が続く。
上記の 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 変換のことである。
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.
適用される変換の型を指定する文字。 変換指定子とその意味は以下の通りである。
成功時には、上記の関数は書き込まれた文字数を返す (文字列の最後を示すために使用するヌルバイトは数に含まれない)。
snprintf() と vsnprintf() は、 size バイトを越える文字数を書き込まない (size には文字列を終端するヌルバイト ('\0') も含まれる)。 この制限によって出力が切り詰められた場合には、 もし十分なスペースがあれば書き込まれたであろう文字の個数 (文字列を終端するヌルバイトを除く) を返す。 従って、返り値が size 以上だった場合、出力が切り詰められたことを意味する (後述の注意も参照のこと)。
エラーが発生した場合は、負の数を返す。
この節で使用されている用語の説明については、 attributes(7) を参照。
| インターフェース | 属性 | 値 |
| printf(), fprintf(), sprintf(), snprintf(), vprintf(), vfprintf(), vsprintf(), vsnprintf() | Thread safety | MT-Safe locale |
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/ に書かれている。
| 2020-11-01 | GNU |