_CrtDbgReport、_CrtDbgReportW
デバッグ メッセージを表示したレポートを生成し、対象となる 3 つの出力先にレポートを送信します (デバッグ バージョンだけ)。
int _CrtDbgReport(
int reportType,
const char *filename,
int linenumber,
const char *moduleName,
const char *format [,
argument] ...
);
int _CrtDbgReportW(
int reportType,
const wchar_t *filename,
int linenumber,
const wchar_t *moduleName,
const wchar_t *format [,
argument] ...
);
パラメーター
reportType
レポートの種類:_CRT_WARN, _CRT_ERROR, and _CRT_ASSERT.filename
アサートまたはレポートの発生したソース ファイル名へのポインター、または NULL。linenumber
アサートまたはレポートの発生したソース ファイルの行番号、または NULL。moduleName
アサートまたはレポートの発生したモジュール名 (.exe または .dll) へのポインター。format
ユーザー メッセージの作成に使用する書式制御文字列へのポインターargument
format で使用されるオプションの代替引数。
戻り値
すべてのレポート出力先に対し、_CrtDbgReport と _CrtDbgReportW は、エラーが発生すると –1 を返し、発生しなければ 0 を返します。 ただし、レポート出力先がデバッグ メッセージ ウィンドウの場合に、ユーザーが [Retry] をクリックすると、これらの関数は 1 を返します。 [デバッグ メッセージ] ウィンドウで [Abort] をクリックすると、これらの関数はすぐに処理を中止し、戻り値を返しません。
_RPT、_RPTF の各デバッグ マクロは、_CrtDbgReport を呼び出し、それぞれのデバッグ レポートを生成します。 このマクロのワイド文字バージョン、_ASSERT[E]、_RPTWn、および _RPTFWn は、_CrtDbgReportW を使用してデバッグ レポートを生成します。 JIT (Just-In-Time) デバッグが有効になっている場合に _CrtDbgReport または _CrtDbgReportW が 1 を返すと、このマクロはデバッガーを起動します。
解説
_CrtDbgReport・_CrtDbgReportWデバッグ レポートの 3 つの異なる宛先に送信することができます。デバッグ レポート ファイル、デバッグ モニター (、Visual Studioデバッガー)、または、デバッグ メッセージ ウィンドウ。 出力先をレポートの種類ごとに指定するために、_CrtSetReportMode と _CrtSetReportFile の 2 つの設定関数が使用されます。 これらの関数を使用すると、1 つ以上の出力先をレポートの種類に応じて個別に制御できます。 たとえば、reportType が _CRT_WARN の場合はレポートをデバッグ モニターのみに送信し、reportType が _CRT_ASSERT の場合はレポートをデバッグ メッセージ ウィンドウとユーザー定義のレポート ファイルに送信するように指定できます。
_CrtDbgReportW 関数は、_CrtDbgReport 関数のワイド文字バージョンです。 すべての出力と文字列パラメーターはワイド文字列です。それ以外はバイト文字バージョンと同じです。
_CrtDbgReport と _CrtDbgReportW は、printf 関数または wprintf 関数で定義した規則と同じ規則を使用し、argument[n] の引数を format の文字列に置き換えることによって、デバッグ レポートに表示するユーザー メッセージを作成します。 これらの関数はデバッグ レポートを生成し、現在のレポート モードと reportType で定義されているレポート ファイルに基づいて出力先を決定します。 デバッグ メッセージ ウィンドウにレポートが送信されると、ウィンドウには filename、lineNumber、および moduleName の情報が表示されます。
選択できるレポート モード、レポート ファイル、および _CrtDbgReport と _CrtDbgReportW の動作結果を次の表に一覧表示します。 これらのオプションは、Crtdbg.h でビット フラグとして定義されています。
レポート モード |
レポート ファイル |
_CrtDbgReport、_CrtDbgReportW の動作 |
|---|---|---|
_CRTDBG_MODE_DEBUG |
適用なし |
Windows OutputDebugString API にメッセージを書き込みます。 |
_CRTDBG_MODE_WNDW |
適用なし |
Windows MessageBox API を呼び出し、メッセージ ボックスを作成します。メッセージ ボックスには、メッセージと [Abort]、[Retry]、[Ignore] の各ボタンが表示されます。 ユーザーが [Abort]、[_CrtDbgReport]、または [_CrtDbgReport] をクリックすると、処理は即座に中止されます。 [Retry] をクリックすると 1 が返され、 [Ignore] をクリックすると実行は続行され、_CrtDbgReport と _CrtDbgReportW の場合は 0 が返されます。 エラー状態のときに [Ignore] をクリックすると、"未定義の動作" が実行される場合があることに注意してください。 |
_CRTDBG_MODE_FILE |
__HFILE |
Windows WriteFile API を使用し、ユーザーが指定した HANDLE にメッセージを書き込みます。ファイル ハンドルの有効性が検査されないため、レポート ファイルのオープンおよび有効なファイル ハンドルの引き渡しはアプリケーション側で実行する必要があります。 |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDERR |
メッセージを stderr に書き込みます。 |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDOUT |
メッセージを stdout に書き込みます。 |
レポートの送信先には、0 ～ 3 か所を指定できます。 レポート モードとレポート ファイルの指定の詳細については、「_CrtSetReportMode」および「_CrtSetReportFile」の各関数を参照してください。 デバッグ マクロおよびレポート関数の使い方の詳細については、「レポート用マクロの使用」を参照してください。
アプリケーションで _CrtDbgReport と _CrtDbgReportW よりさらに柔軟な設定が必要な場合は、独自のレポート関数を作成し、_CrtSetReportHook 関数を使用して C ランタイム ライブラリのレポート機構にフックしてください。
必要条件
ルーチン |
必須ヘッダー |
|---|---|
_CrtDbgReport |
<crtdbg.h> |
_CrtDbgReportW |
<crtdbg.h> |
互換性の詳細については、「C ランタイム ライブラリ」の「互換性」を参照してください。
ライブラリ
C ランタイム ライブラリのデバッグ バージョンのみ。
使用例
// crt_crtdbgreport.c
#include <crtdbg.h>
int main() {
#ifdef _DEBUG
CrtDbgReport(_CRT_ASSERT, NULL, NULL, "some module", NULL);
#endif
}
レポート関数を変更する方法の例については、「crt_dbg2 サンプル : C ランタイムのデバッグのフック関数」を参照してください。