Client Block Hook Functions

If you are interested in validating or reporting the contents of the data that you are storing in _CLIENT_BLOCK blocks, you can write a function specifically for this purpose. The function that you write must have a prototype similar to the following, as defined in crtdbg.h:

void YourClientDump(void *, size_t)

In other words, your hook function should accept a void pointer to the beginning of the user's topic of the allocation block, together with a size_t type value indicating the size of the allocation, and return void. Other than that, its contents are up to you.

Once you have installed it using _CrtSetDumpClient, your hook function will be called every time a _CLIENT_BLOCK block is dumped.

The pointer to your function that you pass to _CrtSetDumpClient is of type _CRT_DUMP_CLIENT, as defined in crtdbg.h:

typedef void (__cdecl *_CRT_DUMP_CLIENT)
   (void *, size_t);

Report Hook Functions

A report hook function, installed using _CrtSetReportHook, is called every time _CrtDbgReport generates a debug report. You can use it, among other things, for filtering reports to focus on specific types of allocations. A report hook function should have a prototype like the following:

int YourReportHook(int nRptType, char *szMsg, int *retVal);

The pointer that you pass to _CrtSetReportHook is of type _CRT_REPORT_HOOK, as defined in crtdbg.h:

typedef int (__cdecl *_CRT_REPORT_HOOK)(int, char *, int *);

When the run-time library calls your hook function, the nRptType argument contains the report's category (_CRT_WARN, _CRT_ERROR, or _CRT_ASSERT), szMsg contains a pointer to a fully assembled report message string, and retVal specifies the value that should be returned by _CrtDbgReport. If the hook handles the message in question completely, so that no further reporting is required, it should return FALSE. If it returns TRUE, then _CrtDbgReport will report the message in the normal way.

Allocation Hook Functions

An allocation hook function, installed using _CrtSetAllocHook, is called every time memory is allocated, re-allocated, or freed. This type of hook can be used for many different purposes. Use it to test how an application handles insufficient memory situations, for example, or to examine allocation patterns, or to log allocation information for later analysis. The following restriction describes using C run-time library functions in an allocation hook function.

An allocation hook function should have a prototype like the following:

int YourAllocHook(int nAllocType, void *pvData,
      size_t nSize, int nBlockUse, long lRequest,
      const unsigned char * szFileName, int nLine )

The pointer that you pass to _CrtSetAllocHook is of type _CRT_ALLOC_HOOK, as defined in crtdbg.h:

typedef int (__cdecl * _CRT_ALLOC_HOOK)
   (int, void *, size_t, int, long, const char *, int);

When the run-time library calls your hook, the nAllocType argument indicates what allocation operation is about to be performed (_HOOK_ALLOC, _HOOK_REALLOC, or _HOOK_FREE). In the case of a free or a reallocation, pvData contains a pointer to the user topic of the block about to be freed. However, in the case of an allocation, this pointer is null, because the allocation has not yet occurred. The remaining arguments contain the size of the allocation in question, its block type, the sequential request number associated with it, and a pointer to the file name and line number in which the allocation was made, if available. After the hook function performs whatever analysis and other tasks its author wants, it must return either TRUE, indicating that the allocation operation can continue, or FALSE, indicating that the operation should fail. A simple hook of this type might check the amount of memory allocated so far, and return FALSE if that amount exceeded a small limit. The application would then experience the kind of allocation errors that would normally occur only when available memory was very low. More complex hooks might keep track of allocation patterns, analyze memory use, or report when specific situations occur.

Allocation Hooks and C Runtime Memory Allocations

An important restriction on allocation hook functions is that they must explicitly ignore _CRT_BLOCK blocks (the memory allocations made internally by C run-time library functions) if they make any calls to C runtime library functions that allocate internal memory. The _CRT_BLOCK blocks can be ignored by including code such as the following at the beginning of your allocation hook function:

if ( nBlockUse == _CRT_BLOCK )
   return( TRUE );

If your allocation hook does not ignore _CRT_BLOCK blocks, then any C run-time library function called in your hook can trap the program in an endless loop. For example, printf makes an internal allocation. If your hook code calls printf, then the resulting allocation will cause your hook to be called again, which will call printf again, and so on until the stack overflows.