vprintf(3)

printf, fprintf, sprintf, snprintf, asprintf, vprintf, vfprintf, vsprintf, vsnprintf, vasprintf − 書式に変換して出力

標準 C ライブラリ (libc, −lc)

#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() は、指定された出力 stream に出力を行います。 sprintf(), snprintf(), vsprintf(), vsnprintf() は、キャラクタ文字列 str に出力を行い ます。 asprintf() と vasprintf() は、 malloc(3) で新しい文字列を動的に割 り当てます。

これらの関数は、 format 文字列による制御に従って出力を行います。この文字 列は、その後の引数 (または stdarg(3) の可変長引数機能でアクセスできる引 数) を出力用に変換する方法を指定します。

この関数は、出力された文字数 (文字列への出力を終了する、最後の ‘\0’ は含 まない) を返します。 snprintf() と vsnprintf() の場合のみ、 size の制限が 無かったとしたら出力されたであろう文字数 (同様に文字列の最後の ‘\0’ は含 まない) を返します。

asprintf() と vasprintf() は、整形された文字列を格納するのに十分な大きさ のバッファを指すポインタを *ret に設定します。割り当てられた領域が不要に なった場合は、このポインタを free(3) に渡して解放してください。十分な領域 を割り当てられない場合、 asprintf() と vasprintf() は -1 を戻し、 ret を NULL ポインタに設定します。

snprintf() と vsnprintf() は、最大で size−1 文字だけ出力文字列に書き込み ます ( size 番目の文字は終端の ‘\0’ になります)。戻り値が size 引数以上で ある場合は、文字列を格納するには短かすぎたため、出力された文字の一部が破 棄されたことになります。

sprintf() と vsprintf() は、 size が無限であると仮定します。

整形文字列は、0 以上の命令から構成されています。この命令には、出力スト リームに変更されずにコピーされる通常文字 (% 以外)、および 0 以上の後続の 引数を取り出す変換指定があります。それぞれの変換指定は、 % 文字から始まり ます。引数は、 (型拡張の後に) 変換指示子に適切に対応する必要があります。 % の後には、以下が順番に現れます。

• 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 (ゼロ) 文字のパディングを指定する。 n 変換を除くすべての変換で は、変換値の左に空白ではなく 0 が付きます。数値変換 (d, i, o, u, i, x, および X) で精度が指定されている場合、 0 フラグは無視されま す。

− 負のフィールド幅を示す − フラグは変換された値がフィールド境界の左 で揃えられる事を示します。 n 変換以外では、変換値の左に空白か 0 が付くのではなく、変換値の右に空白が付きます。 − と 0 を両方とも 指定した場合は 0 が無効になります。

− 空白。符号付き変換 (d, e, E, f, g, G, および i) で作成される正の 数値の前に空白が残ります。

− + 文字。符号付き変換で作成される数値の前に常に符号が付きます。 + と空白を両方とも指定した場合は空白が無効になります。

• 任意の 10 進数文字列。最低フィールド幅を指定します。変換値の文字数が フィールドの幅より少ない場合は、左に空白が付いて (左揃えフラグを指定 した場合は右に空白が付いて) フィールドの幅に合わせられます。

• ピリオド . の次に任意の数字文字列が続く形式の精度。数字文字列を省略し た場合、精度は 0 になります。 d, i, o, u, x, および X 変換では、この 精度の最低桁数が出力されます。 e, E, および f 変換では、小数点以下に この精度の桁数が出力されます。 g および G 変換では、この精度の最大有 効桁数が出力されます。 s 変換では、この精度の最大文字数が文字列から出 力されます。

• オプション文字 h 。後の d, i, o, u, x, および X 変換が short int 引数 か unsigned short int 引数に対応すること、または後の n 変換が short int 引数のポインタに対応することを指定します。

• オプション文字 l (小文字の L)。後の d, i, o, u, x, および X 変換が long int 引数か unsigned long int 引数のポインタに適用されること、ま たは後の n 変換が long int 引数のポインタに対応することを指定します。

• オプション文字 ll (小文字の L が 2 つ)。後の d, i, o, u, x, および X 変換が long long int 引数か unsigned long long int 引数に対応するこ と、または後の n 変換が long long int 引数のポインタに対応することを 指定します。

• オプション文字 q, 。後の d, i, o, u, x, および X 変換が quad int 引数 か unsigned quad int 引数に対応すること、または後の n 変換が quad int 引数のポインタに対応することを指定します。

• オプション文字 L 。後の e, E, f, g, および G 変換が long double 引数 に対応することを指定します。

• 適用する変換の型を指定する文字。

フィールド幅か精度、またはその両方は、アスタリスク ‘*’ 、または数字文字列 の代わりに 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 が仮定されます。精度が 0 である場合、 小数点は出力されません。 E 変換では、文字 E (e ではない) が使用さ れて指数が導入されます。指数には、最低 2 桁が常に含まれます。値が 0 である場合、指数は 00 になります。

f
double 引数が丸められ、 [
−]ddd.ddd, のスタイルで 10 進に変換さ れます。小数点以下の桁数は、精度指定に等しくなります。精度が指定 されていない場合は 6 が仮定されます。精度が 0 である場合、小数点 は出力されません。小数点が出力される場合は、小数点以上に最低 1 桁 が出力されます。

gG
double 引数が、スタイル f か e (G 変換の場合は E) で変換されま す。精度は有効桁数を指定します。精度が指定されていない場合は 6 が 仮定されます。精度が 0 である場合は 1 として扱われます。変換後の 指数が -4 より小さいか精度以上である場合は、スタイル e が使用され ます。後続の 0 は、結果の小数部から削除されます。小数点は、小数点 以下に最低でも 1 桁ある場合に出力されます。

c
int 引数が unsigned char に変換され、変換された文字が出力されま す。

s
char * 引数が、文字型の配列を指すポインタ (文字列へのポインタ) と みなされます。配列の文字は、最後のヌル文字まで出力されます ( NULL 文字は出力されません)。精度が指定されている場合、指定された数以上 は出力されないので、 NULL 文字は必要ありません。精度が指定されて いない場合、または精度が配列のサイズ以上である場合、配列の最後に はヌル文字が必要です。

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/IEC 9899:1990 (‘‘ISO C89’’) に適合しています。

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() インタフェースを使用してください。残念ながら、このインタフェースは移植で きません。

FreeBSD 10.0 June 4, 1993 FreeBSD 10.0