日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.2-RELEASE-K, 8.0-RELEASE-K は、プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.2-RELEASE-K, 8.0-RELEASE-K は、全翻訳済み)
6.4-STABLE-K, 7.2-STABLE-K, 8.0-STABLE-K は現在、 作成中で日々更新されています。 最新の snapshots を元に作成しています。
PRINTF(3) FreeBSD Library Functions Manual PRINTF(3)
名称
printf, fprintf, sprintf, snprintf, asprintf, vprintf, vfprintf,
vsprintf, vsnprintf, vasprintf - フォーマット済み出力変換
書式
#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, ...)
int
asprintf(char **ret, 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)
int
vasprintf(char **ret, const char *format, va_list ap)
解説
printf() ファミリの関数は、以下で説明する format に従って出力を実行しま
す。 printf() と vprintf() は、 stdout に出力を実行します。 fprintf() と
vfprintf() は、指定された出力ストリームに出力を実行します。 sprintf(),
snprintf(), vsprintf(), vsnprintf() は、キャラクタ文字列 str に書き込みを
行ないます。 asprintf() と vasprintf() は、 malloc(3) や realloc(3) で新
しい文字列をダイナミックに割り振ります。
この関数は、 format 文字列の制御に従って出力を実行します。この文字列は、
その後の引数 (または stdarg(3) の可変長引数機能でアクセスできる引数) を出
力用に変換する方法を指定します。
この関数は、出力された文字数 (文字列への出力を終了する、最後の `\0' は含
まない) を戻します。
asprintf() と vasprintf() は、文字列を収容する十分な大きさのバッファを指
すポインタを ret 引数で戻します。記憶域が不要になった場合は、このポインタ
を free(3) に渡して、割り振られた記憶域を解放してください。十分なスペース
を割り振れない場合、 asprintf() と vasprintf() は -1 を戻し、 ret をヌル
ポインタに設定します。
snprintf() と vsnprintf() は、最大で size-1 の文字を出力文字列に書き込み
ます (size 番目の文字は最後の `\0' になります)。戻り値が size 引数以上で
ある場合は、文字列が短すぎたため、出力された文字の一部が破棄されたことに
なります。
sprintf() と vsprintf() は、 size が無限であることを仮定します。
フォーマット文字列は、0 以上の命令から構成されています。この命令には、出
力ストリームに変更されずにコピーされる通常文字 (% 以外)、およびゼロ以上の
後続引数を取り出す変換指定があります。それぞれの変換指定は、文字 % で導入
されます。引数は、タイププロモーション後に変換指示子に適切に対応する必要
があります。 % の後には、以下が順番に現れます。
+o 後に $ が続く 10 進数文字列から構成され、次にアクセスする引数を指定す
る任意のフィールド。このフィールドを指定しないと、最後にアクセスされ
た引数に続く引数が使用されます。引数には 1 から始まる番号が付きます。
フォーマット文字列で、アクセスできない引数がアクセスできる引数に点在
する場合、結果は不定になります。
+o 0 個以上の以下のフラグ
- 値を「代替フォーム」に変換することを指定する # 文字。 c, d, i, n,
p, s, および u 変換の場合、このオプションは効果を発揮しません。 o
変換の場合は、数値の精度が上がり、出力文字列の最初の文字が 0 にな
ります (明確な精度の 0 で 0 が出力される場合を除く)。 x 変換と X
変換の場合は、0 以外の結果の前に文字列 `0x' (X 変換の場合は `0X')
が付きます。 e, E, f, g, および G 変換の場合は、小数点以下がなく
ても小数点が結果に常に含まれます (通常の場合、小数点以下がある場
合にかぎり、変換結果に小数点が付きます)。 g および G 変換の場合
は、後続の 0 が通常の場合のように結果から削除されません。
- 0 のパディングを指定する `0' 文字。 n 変換を除くすべての変換で
は、変換値の左にブランクではなく 0 が付きます。数値変換 (d, i, o,
u, i, x, および X) で精度が指定されている場合、 `0' フラグは無視
されます。
- 負のフィールド幅を示す `-' フラグ。変換値はフィールド境界の左で揃
えられます。 n 変換以外では、変換値の左にブランクか 0 が付くので
はなく、変換値の右にブランクが付きます。 `-' と `0' を両方とも指
定した場合は `0' が無効になります。
- スペース。符号付き変換 (d, e, E, f, g, G, および i) で作成される
正の数値の前にブランクが残ります。
- `+' 文字。符号付き変換で作成される数値の前に常に符号が付きます。
`+' とスペースを両方とも指定した場合はスペースが無効になります。
+o 任意の 10 進数文字列。最低フィールド幅を指定します。変換値の文字数が
フィールドの幅より少ない場合は、左にスペースが付いて (左揃えフラグを
指定した場合は右にスペースが付いて) フィールドの幅に合わせられます。
+o ピリオド `.' の次に任意の数字文字列が続く形式の精度。数字文字列を省略
した場合、精度はゼロになります。 d, i, o, u, x, および X 変換では、こ
の精度の最低桁数が出力されます。 e, E, および f 変換では、小数点以下
にこの精度の桁数が出力されます。 g および G 変換では、この精度の最大
有効桁数が出力されます。 s 変換では、この精度の最大文字数が文字列から
出力されます。
+o オプション文字 h。後の d, i, o, u, x, および X 変換が short int 引数
か unsigned short int 引数に対応すること、または後の n 変換が short
int 引数のポインタに対応することを指定します。
+o オプション文字 l。後の d, i, o, u, x, および X 変換が long int 引数か
unsigned long int 引数のポインタに適用されること、または後の n 変換が
long int 引数のポインタに対応することを指定します。
+o オプション文字 q。後の d, i, o, u, x, および X 変換が quad int 引数か
unsigned quad int 引数に対応すること、または後の n 変換が quad int 引
数のポインタに対応することを指定します。
+o オプション文字 L。後の e, E, f, g, および G 変換が long double 引数に
対応することを指定します。 long double の値が、 VAX コンパイラと
Tahoe コンパイラではサポートされていないことに注意してください。
+o 適用する変換のタイプを指定する文字。
フィールド幅か精度、またはその両方は、アスタリスク `*'、または数字文字列
の代わりに 1 つ以上の 10 進数と `$' が続くアスタリスクで指定できます。こ
の場合、 int 引数はフィールド幅か精度を提供します。負のフィールド幅は、正
のフィールド幅が続く左揃えフラグとして扱われます。負の精度は、欠落してい
るものとして扱われます。1 つのフォーマット命令に位置引数 (nn$) と位置以外
の引数が混在している場合、結果は未定義になります。
変換指示子とその意味は次のとおりです。
diouxX int 引数 (または適切な可変引数) が、符号付き 10 進 (d と i)、符号
なし 8 進 (o)、符号なし 10 進 (u)、符号なし 16 進 (x と X) に変換
されます。 x 変換には文字 abcdef、 X 変換には文字 ABCDEF が使用さ
れます。精度は、出力する最低桁数を指定します。変換値で少ない桁し
か必要ない場合は、左に 0 が付きます。
DOU long int 引数が、符号付き 10 進、符号なし 8 進、符号なし 10 進
に、それぞれのフォーマットが ld, lo, lu であるかのように変換され
ます。この変換文字には問題があるので、最終的には出力されません。
eE double 引数が丸められ、 [-]d.ddde+-dd のスタイルに変換されます。
小数点以上は 1 桁で、小数点以下の桁数は精度と等しくなります。精度
が指定されていない場合は 6 が仮定されます。精度がゼロである場合、
小数点は出力されません。 E 変換では、文字 E (e ではない) が使用さ
れて指数が導入されます。指数には、最低 2 桁が常に含まれます。値が
0 である場合、指数は 00 になります。
f double 引数が丸められ、 [-]ddd.ddd のスタイルで 10 進に変換されま
す。小数点以下の桁数は、精度指定に等しくなります。精度が指定され
ていない場合は 6 が仮定されます。精度が 0 である場合、小数点は出
力されません。小数点が出力される場合は、小数点以上に最低 1 桁が出
力されます。
g double 引数が、スタイル f か e (G 変換の場合は E) で変換されま
す。精度は有効桁数を指定します。精度が指定されていない場合は 6 が
仮定されます。精度がゼロである場合は 1 として扱われます。変換後の
指数が -4 より小さいか精度以上である場合は、スタイル e が使用され
ます。後続のゼロは、結果の小数部から削除されます。小数点は、小数
点以下に最低でも 1 桁ある場合に出力されます。
c int 引数が unsigned char に変換され、変換された文字が出力されま
す。
s ``char *'' 引数が、文字型の配列を指すポインタ (文字列へのポイン
タ) とみなされます。配列の文字は、最後のナル文字まで出力されます
(ナル文字は出力されません)。精度が指定されている場合、指定された
数以上は出力されないので、ナル文字は必要ありません。精度が指定さ
れていない場合、または精度が配列のサイズ以上である場合、配列の最
後にはナル文字が必要です。
p ``void *'' ポインタ引数が、16 進で `(%#x' か `%#lx' でのように)
出力されます。
n これまでに出力された文字数が、 ``int *'' ポインタ引数 (または可変
ポインタ引数) が指定する整数に保存されます。引数は変換されませ
ん。
% `%' が出力されます。引数は変換されません。完全な変換指定は `%%'
です。
フィールド幅が存在しない場合、またはフィールド幅が小さい場合でも、フィー
ルドは切り捨てられません。変換結果がフィールド幅より大きい場合、フィール
ドは変換結果を収容できるようになるまで拡張されます。
例
weekday と month が文字列へのポインタである場合に `Sunday, July 3, 10:02'
という形式で日付と時刻を出力する場合:
#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
pi を小数第 5 位まで出力する場合:
#include <math.h>
#include <stdio.h>
fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
128 バイトの文字列を割り振り、そこに出力する場合:
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *newfmt(const char *fmt, ...)
{
char *p;
va_list ap;
if ((p = malloc(128)) == NULL)
return (NULL);
va_start(ap, fmt);
(void) vsnprintf(p, 128, fmt, ap);
va_end(ap);
return (p);
}
関連項目
printf(1), scanf(3)
規格
fprintf(), printf(), sprintf(), vprintf(), vfprintf(), および vsprintf()
関数は、 ISO 9899: 1990 (``ISO C'') に準拠しています。
歴史
asprintf() 関数と vasprintf() 関数は、GNU C ライブラリに追加されました。
これは、 FreeBSD 2.2 で Peter Wemm <peter@FreeBSD.org> によって実現されま
したが、 OpenBSD 2.3 では後に Todd C. Miller <Todd.Miller@courtesan.com>
のシステムで置き換えられました。
バグ
変換フォーマット %D, %O, および %U は標準的ではなく、下位互換性を保つため
に提供されています。 %p フォーマットに ( `0' フラグか精度を指定すること
で) 0 をパディングすること、 %n 変換と %p 変換で `#' フラグを指定するこ
と、 %Ld のような無意味な組み合わせは標準的でありません。このような組み合
わせは避けてください。
sprintf() と vsprintf() では無限に長い文字列が仮定されるので、呼び出し側
では実際のスペースをオーバフローしないように注意する必要があります。オー
バフローしないことを保証することは困難です。安全のため、代わりに
snprintf() インタフェースを使用してください。残念ながら、このインタフェー
スは移植できません。
BSD June 4, 1993 4