Edit

Debug routines

  • Article

The debug version of the C runtime 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

Debug versions of the C runtime library routines

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.

Routine Use
_ASSERT Evaluate an expression and generates a debug report when the result is FALSE
_ASSERTE Similar to _ASSERT, but includes the failed expression in the generated report
_CrtCheckMemory Confirm the integrity of the memory blocks allocated on the debug heap
_CrtDbgBreak Sets a break point.
_CrtDbgReport, _CrtDbgReportW Generate a debug report with a user message and send the report to three possible destinations
_CrtDoForAllClientObjects Call an application-supplied function for all _CLIENT_BLOCK types on the heap
_CrtDumpMemoryLeaks Dump all of the memory blocks on the debug heap when a significant memory leak has occurred
_CrtIsMemoryBlock Verify that a specified memory block is located within the local heap and that it has a valid debug heap block type identifier
_CrtIsValidHeapPointer Verifies that a specified pointer is in the local heap
_CrtIsValidPointer Verify that a specified memory range is valid for reading and writing
_CrtMemCheckpoint Obtain the current state of the debug heap and store it in an application-supplied _CrtMemState structure
_CrtMemDifference Compare two memory states for significant differences and return the results
_CrtMemDumpAllObjectsSince Dump information about objects on the heap since a specified checkpoint was taken or from the start of program execution
_CrtMemDumpStatistics Dump the debug header information for a specified memory state in a user-readable form
_CrtReportBlockType Returns the block type/subtype associated with a given debug heap block pointer.
_CrtSetAllocHook Install a client-defined allocation function by hooking it into the C run-time debug memory allocation process
_CrtSetBreakAlloc Set a breakpoint on a specified object allocation order number
_CrtSetDbgFlag Retrieve or modify the state of the _crtDbgFlag flag to control the allocation behavior of the debug heap manager
_CrtSetDumpClient Install an application-defined function that is called every time a debug dump function is called to dump _CLIENT_BLOCK type memory blocks
_CrtSetReportFile Identify the file or stream to be used as a destination for a specific report type by _CrtDbgReport
_CrtSetReportHook Install a client-defined reporting function by hooking it into the C run-time debug reporting process
_CrtSetReportHook2, _CrtSetReportHookW2 Installs or uninstalls a client-defined reporting function by hooking it into the C run-time debug reporting process.
_CrtSetReportMode Specify the general destination(s) for a specific report type generated by _CrtDbgReport
_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.
_RPTF[0,1,2,3,4] Similar to the _RPTn macros, but provides the source file name and line number where the report request originated
_calloc_dbg Allocate a specified number of memory blocks on the heap with extra space for a debugging header and overwrite buffers
_expand_dbg Resize a specified block of memory on the heap by expanding or contracting the block
_free_dbg Free a block of memory on the heap
_fullpath_dbg, _wfullpath_dbg Create an absolute or full path name for the specified relative path name, using _malloc_dbg to allocate memory.
_getcwd_dbg, _wgetcwd_dbg Get the current working directory, using _malloc_dbg to allocate memory.
_malloc_dbg Allocate a block of memory on the heap with extra space for a debugging header and overwrite buffers
_msize_dbg Calculate the size of a block of memory on the heap
_realloc_dbg Reallocate a specified block of memory on the heap by moving and/or resizing the block
_strdup_dbg, _wcsdup_dbg Duplicates a string, using _malloc_dbg to allocate memory.
_tempnam_dbg, _wtempnam_dbg Generate names you can use to create temporary files, using _malloc_dbg to allocate memory.

C runtime routines that aren't available in source code form

The debugger can be used to step through the source code for most of the C runtime routines during the debugging process. However, Microsoft considers some technology to be proprietary and, therefore, doesn't provide the source code for a subset of 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.

acos
acosh
asin
asinh
atan, atan2
atanh
Bessel functions
_cabs
ceil
_chgsign
_clear87, _clearfp
_control87, _controlfp

copysign
cos
cosh
Exp
fabs
_finite
floor
fmod
_fpclass
_fpieee_flt
_fpreset
frexp

_hypot
_isnan
ldexp
log
_logb
log10
longjmp
_matherr
modf
_nextafter
pow
printf_s

printf
_scalb
scanf_s
scanf
setjmp
sin
sinh
sqrt
_status87, _statusfp
tan
tanh

Although source code is available for most of the printf and scanf routines, they make an internal call to another routine for which source code isn't provided.

Routines that behave differently in a debug build of an application

Some C run-time functions and C++ operators behave differently when called from a debug build of an application. (You can create a debug build of an application 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.

C abort routine

C assert routine

C++ delete operator

C++ new operator

See also

Universal C runtime routines by category
Runtime error checking