printf printfの概要

ウィキペディア

printf

出典: フリー百科事典『ウィキペディア（Wikipedia）』 (2024/07/06 14:45 UTC 版)

この関数は、第1引数に与えられた文字列を出力する。C言語の他の単純な入出力関数に比べ、比較的複雑な構造を持っており、第1引数の文字列のなかで書式を指定することで、第2引数以降の任意の数の引数（可変長引数）を、書式に従って出力することができる。また、整数型（int型）の戻り値を持ち、出力に成功した場合には転送したバイト数、出力に失敗した場合には負数を返却する。

形式

#include <stdio.h>
int printf(const char * restrict format, ...);

書式化文字列

上記形式における第一引数には、それに続く実引数の変換方法を指定する。書式化文字列には、通常のマルチバイト文字または%で始まる変換指定のいずれかの指令を0個以上含む。マルチバイト文字が含まれ、かつ文字コードがシフトシーケンスに依存する場合には、書式化文字列は初期シフト状態で始まり、初期シフト状態で終わらなければならない。書式指定を行う%〜それぞれを書式指定子と呼ぶ。

変換指定

変換指定は次の形式をとる。（[ ]内は省略可能）

%[引数順][フラグ][最小フィールド幅][.精度][長さ修飾子]変換指定子

引数順 (POSIX)

これは標準C規格の仕様ではなく、POSIXで規定されている拡張である。

書式文字列において%の代わりに%m$を記述することで、続く可変長引数のうちどれを使うかを番号mで指定できる。 例えば、

const char* fmt = "Invalid command %1$s at line %2$d.\n";
const char* cmd = "hoge";
const int lineNumber = 20;
printf(fmt, cmd, lineNumber);

とした場合、

Invalid command hoge at line 20.

と表示される。これだけならば大きな意味はないが、例えばメッセージを翻訳（ローカライズ）する際、

const char* fmt = "%2$d行目のコマンド %1$s は不正です。\n";

というように書式文字列だけをローカライズする^{[注釈 1]}ことで、可変長引数の指定順を変更せずに、

20行目のコマンド hoge は不正です。

という自然な語順の出力を得ることができる^{[注釈 2]}。

フラグ

変換指定のフラグは以下の通り。

フラグ	意味
-	フィールドの左寄せ
+	常に符号を出力
空白	数値が正または 0 の場合は符号の代わりに空白を出力
#	代替形式。基数を表すプレフィックスの出力等
0	出力文字数が最小フィールド幅未満の場合は'0'を出力

長さ修飾子

修飾子	意味	導入バージョン
hh	実引数はchar型	C99以降
h	実引数はshort型	全バージョン
l（エル）	実引数はlong型、wint_t型、wchar_t型またはdouble型[注釈 3]	wint_tおよびwchar_tについてはC95以降、doubleについてはC99以降
ll（エルエル）	実引数はlong long型	C99以降
j	実引数はintmax_t型	C99以降
z	実引数はsize_t型	C99以降
t	実引数はptrdiff_t型	C99以降
L	実引数はlong double型	全バージョン

なお、C99で追加されたint32_tやint64_tなどのビット数が指定された整数型の実引数に対して、これらの長さ修飾子を直接使用した場合の動作は未定義である。仮に特定の実装では期待通り動作したとしても、データ型モデルによっては移植の際に非互換が生じることもある^{[注釈 4]}。これらの固定幅の整数型を実引数として使用する際は、明示的な型キャストをするか、inttypes.hヘッダーに定義されているPRIで始まるマクロを利用する必要がある^[1][2]。

変換指定子

指定子	意味	導入バージョン
d, i	10進符号付き整数	全バージョン
u	10進符号無し整数	全バージョン
o	8進符号無し整数	全バージョン
x, X	16進符号無し整数（ X は大文字で出力）	全バージョン
e, E	指数形式浮動小数点数（ E は大文字で出力）	全バージョン
f, F	小数形式浮動小数点数（ F は大文字で出力）	全バージョン
g, G	e または f 形式のうち適した方（ G は大文字で出力）	全バージョン
a, A	16進浮動小数点（ A は大文字で出力）	C99以降
c	文字	全バージョン
s	文字列	全バージョン
p	ポインタの値	全バージョン
n	整数変数に出力済み文字数を格納	全バージョン
%	'%'の出力	全バージョン

関連する関数

fprintf

fprintfは、引数にファイルポインタfpが追加され、標準出力の代わりにfpへ出力する変種である。

#include <stdio.h>
int fprintf(FILE * restrict fp, const char * restrict format, ...);

sprintf, snprintf

sprintfとsnprintfは、引数にchar配列の要素へのポインタstrが追加されたもので、標準出力の代わりにstrへ出力する変種である。snprintfは、さらにstrに書き込んで良い文字数を指定する引数が追加されたものであるが、Cの標準規格に収録されたのはC99からである。

#include <stdio.h>
int sprintf(char * restrict str, const char * restrict format, ...);
int snprintf(char * restrict str, size_t size, const char * restrict format, ...);

wprintf, fwprintf, swprintf

wprintf, fwprintf, swprintfは、それぞれprintf, fprintf, snprintfに対応し、ワイド文字を使用するものである。C95で標準化された。sprintfに直接対応するワイド文字バージョンの関数（出力バッファサイズを受け取らない関数）は存在しない^{[注釈 5]}。

#include <stdio.h> /* または wchar.h */
int wprintf(const wchar_t * restrict format, ...);
int fwprintf(FILE * restrict fp, const wchar_t * restrict format, ...);
int swprintf(wchar_t * restrict str, size_t size, const wchar_t * restrict format, ...);

va_listを引数に取るもの

ここまでに挙げたprintfとその変種に対して、可変個引数部分をva_listに変化させた種類が存在する。それぞれ、関数名の頭にvを付けた名称となっている。vsnprintfはC99で標準化された。

#include <stdio.h>
int vprintf(const char * restrict format, va_list args);
int vfprintf(FILE * restrict fp, const char * restrict format, va_list args);
int vsprintf(char * restrict str, const char * restrict format, va_list args);
int vsnprintf(char * restrict str, size_t size, const char * restrict format, va_list args);

#include <stdio.h> /* または wchar.h */
int vwprintf(const wchar_t * restrict format, va_list args);
int vfwprintf(FILE * restrict fp, const wchar_t * restrict format, va_list args);
int vswprintf(wchar_t * restrict str, size_t size, const wchar_t * restrict format, va_list args);

安全性を向上させたもの

C11のAnnex K Bounds‐checking interfacesで規定された、安全性を向上させた種類が存在する。それぞれ、関数名の末尾に_sを付けた名称となっている。これらの関数は、__STDC_WANT_LIB_EXT1__を1に定義した上で対応するヘッダーをインクルードすると宣言される。

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <wchar.h>

int printf_s(const char * restrict format, ...);
int fprintf_s(FILE * restrict fp, const char * restrict format, ...);
int sprintf_s(char * restrict str, rsize_t size, const char * restrict format, ...);
int snprintf_s(char * restrict str, rsize_t size, const char * restrict format, ...);
int vprintf_s(const char * restrict format, va_list arg);
int vfprintf_s(FILE * restrict fp, const char * restrict format, va_list arg);
int vsprintf_s(char * restrict str, rsize_t size, const char * restrict format, va_list arg);
int vsnprintf_s(char * restrict str, rsize_t size, const char * restrict format, va_list arg);

int wprintf_s(const wchar_t * restrict format, ...);
int fwprintf_s(FILE * restrict fp, const wchar_t * restrict format, ...);
int swprintf_s(wchar_t * restrict str, rsize_t size, const wchar_t * restrict format, ...);
int snwprintf_s(wchar_t * restrict str, rsize_t size, const wchar_t * restrict format, ...);
int vwprintf_s(const wchar_t * restrict format, va_list arg);
int vfwprintf_s(FILE * restrict fp, const wchar_t * restrict format, va_list arg);
int vswprintf_s(wchar_t * restrict str, rsize_t size, const wchar_t * restrict format, va_list arg);
int vsnwprintf_s(wchar_t * restrict str, rsize_t size, const wchar_t * restrict format, va_list arg);

以下のような機能が追加されている。

• FILE*や文字列の引数（%sに対応する可変長引数部分の引数も含む）に対するNULLポインタチェック
• 出力先バッファサイズのチェック
• %n書式の禁止

エラーは実行時に検出され、現在設定されている制約ハンドラー (constraint handler) 関数が呼ばれる。

Windows API

Microsoft Windows用のWindows APIには、sprintf()やsnprintf()などによく似た名前の関数として以下のようなAPIが用意されている^[5][6]。

// winuser.h
int wsprintfA(LPSTR unnamedParam1, LPCSTR unnamedParam2, ...);
int wsprintfW(LPWSTR unnamedParam1, LPCWSTR unnamedParam2, ...);
int wvsprintfA(LPSTR unnamedParam1, LPCSTR unnamedParam2, va_list arglist);
int wvsprintfW(LPWSTR unnamedParam1, LPCWSTR unnamedParam2, va_list arglist);
// shlwapi.h
int wnsprintfA(PSTR pszDest, int cchDest, PCSTR pszFmt, ...);
int wnsprintfW(PWSTR pszDest, int cchDest, PCWSTR pszFmt, ...);
int wvnsprintfA(PSTR pszDest, int cchDest, PCSTR pszFmt, va_list arglist);
int wvnsprintfW(PWSTR pszDest, int cchDest, PCWSTR pszFmt, va_list arglist);

ここで、LPSTRとPSTRはchar*、LPCSTRとPCSTRはconst char*、LPWSTRとPWSTRはwchar_t*、LPCWSTRとPCWSTRはconst wchar_t*に相当するtypedef型エイリアスである。Wサフィックスはワイド文字によるUnicode文字セット、AサフィックスはANSIマルチバイト文字セット（MBCS）を意味する。プロジェクトのUnicode対応設定（マクロシンボルUNICODEの定義有無）によって関数の実装がW版またはA版に切り替わるwsprintfマクロやwnsprintfマクロなども用意されている。

いずれもfloatやdoubleといった浮動小数点数型の書式化には対応しておらず、C/C++の標準ライブラリ関数とは互換性がない。Cランタイムライブラリ (CRT) に依存せず、Windows環境限定で標準的に使えることがメリットだが、これらの使用は推奨されておらず、<strsafe.h>で定義されているセーフ文字列関数の使用が推奨されている^[7]。

なお、Windows API関数の呼び出し規約は、ほぼすべて_stdcall（__stdcall、WINAPI / STDAPICALLTYPE）であるが、上記のうち可変長引数...を受け取るAPI関数は例外的に_cdecl（__cdecl、WINAPIV / STDAPIVCALLTYPE）となっている。x86の場合は引数の受け渡し動作が呼び出し規約に左右される。