tail head cat sleep
QR code linking to this page

manページ  — PRINTF

名称

printf, vprintf – 書式に変換して出力

内容

ライブラリ

Standard C Library (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, Ns, -1 文字だけ出力文字列に書き込みます ( size 番目の文字は終端の ‘\0’ になります)。 戻り値が size 引数以上である場合は、文字列を格納するには短かすぎたため、 出力された文字の一部が破棄されたことになります。

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

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

フィールド幅か精度、またはその両方は、アスタリスク ‘*’ 、または数字文字列の代わりに 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 .ddd e±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 * ポインタ引数 (または可変ポインタ引数) が指定する整数に保存されます。 引数は変換されません。
% %’ が出力されます。変換される引数はありません。 完全な変換指定は ‘%%’ です。

フィールド幅が存在しない場合、またはフィールド幅が小さい場合でも、 フィールドは切り捨てられません。変換結果がフィールド幅より大きい場合、 フィールドは変換結果を収容できるようになるまで拡張されます。

weekdaymonth が文字列へのポインタである場合に "Sunday, July 3, 10:02" という形式で日付と時刻を出力する場合:
#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
        weekday, month, day, hour, min);

π を小数第 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 C90") に適合しています。

歴史

asprintf() 関数と vasprintf() 関数は、 GNU C ライブラリに追加されました。これは、 FreeBSD 2.2 で Peter Wemm <peter@FreeBSD.org> によって実装されましたが、 OpenBSD 2.3 では後に Todd C. Miller <Todd.Miller@courtesan.com> のシステムで置き換えられました。

バグ

変換形式 %D, %O, および は標準的ではなく、下位互換性を保つために提供されています。 %p 形式に ( 0 フラグか精度を指定することで) 0 をパディングすること、 %n 変換と %p 変換で # フラグを指定すること、 %Ld のような無意味な組み合わせは標準的でありません。 このような組み合わせは避けてください。

sprintf()vsprintf() では無限に長い文字列が仮定されるので、 呼び出し側では実際の空間を オーバフローしないように注意する必要があります。 オーバフローしないことを保証することは困難です。 安全のため、代わりに snprintf() インタフェースを使用してください。 残念ながら、このインタフェースは移植できません。


PRINTF (3) June 4, 1993

tail head cat sleep
QR code linking to this page


このマニュアルページサービスについてのご意見は Ben Bullock にお知らせください。 Privacy policy.

With features like these, who needs bugs?
— Henry Spencer