_CrtDbgReport, _CrtDbgReportW
Создает отчет с сообщением об отладке и отправляет его в три возможных назначения (только отладочная версия).
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, если ошибки отсутствуют. Однако, если назначение отчета — окно с сообщением об отладке, а пользователь нажимает кнопку Повторить, эти функции возвращают значение 1. Если пользователь нажимает кнопку Прервать в окне с сообщением об отладке, эти функции немедленно прерываются и не возвращают значение.
Макросы отладки _RPT, _RPTF вызывают _CrtDbgReport для создания отчетов об отладке. Версии этих макросов с расширенными символами, также как и _ASSERT[E], _RPTWn и _RPTFWn, используют _CrtDbgReportW для создания отчетов об отладке. Если функция _CrtDbgReport или _CrtDbgReportW возвращает значение 1, эти макросы запускают отладчик при условии, что включена JIT-отладка.
Заметки
_CrtDbgReport и _CrtDbgReportW могут отправлять отчет об отладке в три разных назначения: файл отчета об отладке, монитор отладки (отладчик Visual Studio) или окно с сообщением об отладке. Две функции настройки, _CrtSetReportMode и _CrtSetReportFile, используются для задания назначения (назначений) для каждого типа отчета. Эти функции позволяют управлять назначением или назначениями для каждого типа отчета по отдельности. Например, можно указать, что reportType типа _CRT_WARN можно отправлять только в монитор отладки, а reportType типа _CRT_ASSERT — в окно с сообщением об отладке и пользовательский файл отчета.
_CrtDbgReportW — версия _CrtDbgReport с расширенными символами. Все выходные данные и параметры строки отображаются как строки расширенных символов; в противном случае — аналогично версии с однобайтовыми символами.
_CrtDbgReport и _CrtDbgReportW создают сообщение для пользователя для отчета об отладке, подставляя аргументы argument[n] в строку format, используя правила, определенные функциями printf и wprintf. Затем эти функции создают отчет об отладке и определяют назначение (назначения) в зависимости от текущих режимов отчета и файла, заданных для reportType. Когда отчет отправляется в окно с сообщением об отладке, filename, lineNumber и moduleName включаются в набор сведений, которые отображаются в окне.
В таблице ниже приведен список доступных вариантов для режима или режимов отчета и файла, а также поведение, которое является результатом функций _CrtDbgReport и _CrtDbgReportW. Эти параметры определены как битовые флаги в <crtdbg.h>.
Режим отчета |
Файл отчета |
Поведение _CrtDbgReport, _CrtDbgReportW |
|---|---|---|
_CRTDBG_MODE_DEBUG |
Неприменимо |
Создает сообщение, используя API Windows OutputDebugString. |
_CRTDBG_MODE_WNDW |
Неприменимо |
Вызывает API Windows MessageBox для создания окна сообщения, в котором будет отображаться сообщение вместе с кнопками Прервать, Повторить и Пропустить. Если пользователь нажимает кнопку Прервать, функция _CrtDbgReport или _CrtDbgReport немедленно прерывается. Если пользователь нажимает кнопку Повторить, функция возвращает значение 1. Если пользователь нажимает кнопку Пропустить, выполнение продолжается и функции _CrtDbgReport и _CrtDbgReportW возвращают значение 0. Учтите, что нажатие кнопки Пропустить при наличии условия ошибки часто приводит к возникновению "неопределенного поведения". |
_CRTDBG_MODE_FILE |
__HFILE |
Записывает сообщение в предоставленный пользователем HANDLE, используя API Windows WriteFile, и не проверяет допустимость дескриптора файла; приложение отвечает за открытие файла отчета и передачу допустимого дескриптора файла. |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDERR |
Записывает сообщение в stderr. |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDOUT |
Записывает сообщение в stdout. |
Этот отчет можно отправить в одно, два или три назначения (или ни в одно из назначений). Дополнительные сведения о задании режима (режимов) и файла отчета см. в описании функций _CrtSetReportMode и _CrtSetReportFile. Дополнительные сведения об использовании макросов отладки и функций отчетов см. в разделе Макросы для создания отчетов.
Если приложению требуется больше гибкости, чем могут обеспечить функции _CrtDbgReport и _CrtDbgReportW, можно написать собственную функцию создания отчетов и подключить ее к механизму создания отчетов библиотеки времени выполнения языка C, используя функцию _CrtSetReportHook.
Требования
Подпрограмма |
Обязательный заголовок |
|---|---|
_CrtDbgReport |
<crtdbg.h> |
_CrtDbgReportW |
<crtdbg.h> |
_CrtDbgReport и _CrtDbgReportW являются расширениями Майкрософт. Дополнительные сведения см. в разделе Совместимость.
Библиотеки
Только отладочные версии библиотек времени выполнения языка C.
Пример
// crt_crtdbgreport.c
#include <crtdbg.h>
int main(int argc, char *argv[]) {
#ifdef _DEBUG
_CrtDbgReport(_CRT_ASSERT, __FILE__, __LINE__, argv[0], NULL);
#endif
}
Примеры изменения функций создания отчетов см. в разделе crt_dbg2.