_CrtDbgReport、_CrtDbgReportW
更新 : 2007 年 11 月
デバッグ メッセージを表示したレポートを生成し、対象となる 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、および _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 は、デバッグ レポート ファイル、デバッグ モニタ (Visual Studio デバッガ)、またはデバッグ メッセージ ウィンドウの 3 つの出力先にデバッグ レポートを送信できます。出力先をレポートの種類ごとに指定するために、_CrtSetReportMode と _CrtSetReportFile の 2 つの設定関数が使用されます。これらの関数を使用すると、1 つ以上の出力先をレポートの種類に応じて個別に制御できます。たとえば、reportType が _CRT_WARN の場合はレポートをデバッグ モニタのみに送信し、reportType が _CRT_ASSERT の場合はレポートをデバッグ メッセージ ウィンドウとユーザー定義のレポート ファイルに送信するように指定できます。
Visual C++ 2005 では、_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 ランタイムのデバッグのフック関数」を参照してください。