Debug Routines

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

The debug version of the C run-time library supplies many diagnostic services that make debugging programs easier and allow developers to:

  • Step directly into run-time functions during debugging

  • Resolve assertions, errors, and exceptions

  • Trace heap allocations and prevent memory leaks

  • Report debug messages to the user

To use these routines, the _DEBUG flag must be defined. All of these routines do nothing in a retail build of an application. For more information on how to use the new debug routines, see CRT Debugging Techniques.

Debug Versions of the C Run-Time Library Routines

RoutineUse.NET Framework equivalent
_ASSERTEvaluate an expression and generates a debug report when the result is FALSESystem::Diagnostics::Debug::Assert
_ASSERTESimilar to _ASSERT, but includes the failed expression in the generated reportSystem::Diagnostics::Debug::Assert
_CrtCheckMemoryConfirm the integrity of the memory blocks allocated on the debug heapSystem::Diagnostics::PerformanceCounter
_CrtDbgBreakSets a break point.Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtDbgReport, _CrtDbgReportWGenerate a debug report with a user message and send the report to three possible destinationsSystem::Diagnostics::Debug::Write, System::Diagnostics::Debug::Writeline, System::Diagnostics::Debug::WriteIf, System::Diagnostics::Debug::WriteLineIf
_CrtDoForAllClientObjectsCall an application-supplied function for all _CLIENT_BLOCK types on the heapNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtDumpMemoryLeaksDump all of the memory blocks on the debug heap when a significant memory leak has occurredNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtIsMemoryBlockVerify that a specified memory block is located within the local heap and that it has a valid debug heap block type identifierNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtIsValidHeapPointerVerifies that a specified pointer is in the local heapNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtIsValidPointerVerify that a specified memory range is valid for reading and writingNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtMemCheckpointObtain the current state of the debug heap and store it in an application-supplied _CrtMemState structureNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtMemDifferenceCompare two memory states for significant differences and return the resultsNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtMemDumpAllObjectsSinceDump information about objects on the heap since a specified checkpoint was taken or from the start of program executionNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtMemDumpStatisticsDump the debug header information for a specified memory state in a user-readable formSystem::Diagnostics::PerformanceCounter
_CrtReportBlockTypeReturns the block type/subtype associated with a given debug heap block pointer.Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtSetAllocHookInstall a client-defined allocation function by hooking it into the C run-time debug memory allocation processNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtSetBreakAllocSet a breakpoint on a specified object allocation order numberNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtSetDbgFlagRetrieve or modify the state of the _crtDbgFlag flag to control the allocation behavior of the debug heap managerNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtSetDumpClientInstall an application-defined function that is called every time a debug dump function is called to dump _CLIENT_BLOCK type memory blocksNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtSetReportFileIdentify the file or stream to be used as a destination for a specific report type by _CrtDbgReportNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtSetReportHookInstall a client-defined reporting function by hooking it into the C run-time debug reporting processNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtSetReportHook2, _CrtSetReportHookW2Installs or uninstalls a client-defined reporting function by hooking it into the C run-time debug reporting process.Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_CrtSetReportModeSpecify the general destination(s) for a specific report type generated by _CrtDbgReportNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_RPT[0,1,2,3,4]Track the application's progress by generating a debug report by calling _CrtDbgReport with a format string and a variable number of arguments. Provides no source file and line number information.Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_RPTF[0,1,2,3,4]Similar to the _RPTn macros, but provides the source file name and line number where the report request originatedNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_calloc_dbgAllocate a specified number of memory blocks on the heap with additional space for a debugging header and overwrite buffersNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_expand_dbgResize a specified block of memory on the heap by expanding or contracting the blockNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_free_dbgFree a block of memory on the heapNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_fullpath_dbg, _wfullpath_dbgCreate an absolute or full path name for the specified relative path name, using _malloc_dbg to allocate memory.System::IO::File::Create
_getcwd_dbg, _wgetcwd_dbgGet the current working directory, using _malloc_dbg to allocate memory.Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_malloc_dbgAllocate a block of memory on the heap with additional space for a debugging header and overwrite buffersNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_msize_dbgCalculate the size of a block of memory on the heapNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_realloc_dbgReallocate a specified block of memory on the heap by moving and/or resizing the blockNot applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
_strdup_dbg, _wcsdup_dbgDuplicates a string, using _malloc_dbg to allocate memory.System::String::Clone
_tempnam_dbg, _wtempnam_dbgGenerate names you can use to create temporary files, using _malloc_dbg to allocate memory.Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

The debug routines can be used to step through the source code for most of the other C run-time routines during the debugging process. However, Microsoft considers some technology to be proprietary and, therefore, does not provide the source code for these routines. Most of these routines belong to either the exception handling or floating-point processing groups, but a few others are included as well. The following table lists these routines.

C Run-Time Routines That Are Not Available in Source Code Form

acos, acosf, acosl_fpclass_nextafter
asin_fpieee_fltpow
atan, atan2_fpresetprintf, _printf_l, wprintf, _wprintf_l, printf_s, _printf_s_l, wprintf_s, _wprintf_s_l*
_cabsfrexp_scalb
ceil_hypotscanf, _scanf_l, wscanf, _wscanf_l, scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l*
_chgsign, _chgsignf, _chgsignl_isnansetjmp
_clear87, _clearfp_j0sin
_control87, _controlfp, __control87_2_j1sinh
copysign, copysignf, copysignl, _copysign, _copysignf, _copysignl_jnsqrt
cosldexp_status87, _statusfp
coshlogtan
Explog10tanh
fabs_logb_y0
_finitelongjmp_y1
floor_matherr_yn
fmodmodf

* Although source code is available for most of this routine, it makes an internal call to another routine for which source code is not provided.

Some C run-time functions and C++ operators behave differently when called from a debug build of an application. (Note that a debug build of an application can be done by either defining the _DEBUG flag or by linking with a debug version of the C run-time library.) The behavioral differences usually consist of extra features or information provided by the routine to support the debugging process. The following table lists these routines.

Routines that Behave Differently in a Debug Build of an Application

C abort routineC++ delete operator
C assert routineC++ new operator

Run-Time Routines by Category
Run-Time Error Checking

Show: