|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer|
Installs a client-defined allocation function by hooking it into the C run-time debug memory allocation process (debug version only).
_CRT_ALLOC_HOOK _CrtSetAllocHook( _CRT_ALLOC_HOOK allocHook );
- New client-defined allocation function to hook into the C run-time debug memory allocation process.
Returns the previously defined allocation hook function.
_CrtSetAllocHook allows an application to hook its own allocation function into the C run-time debug library memory allocation process. As a result, every call to a debug allocation function to allocate, reallocate, or free a memory block triggers a call to the application's hook function. _CrtSetAllocHook provides an application with an easy method for testing how the application handles insufficient memory situations, the ability to examine allocation patterns, and the opportunity to log allocation information for later analysis. When _DEBUG is not defined, calls to _CrtSetAllocHook are removed during preprocessing.
The _CrtSetAllocHook function installs the new client-defined allocation function specified in allocHook and returns the previously defined hook function. The following example demonstrates how a client-defined allocation hook should be prototyped:
int YourAllocHook( int allocType, void *userData, size_t size, int blockType, long requestNumber, const unsigned char *filename, int lineNumber);
allocType argument specifies the type of allocation operation (_HOOK_ALLOC, _HOOK_REALLOC, _HOOK_FREE) that triggered the call to the allocation's hook function. When the triggering allocation type is _HOOK_FREE,
userData is a pointer to the user data section of the memory block about to be freed. However, when the triggering allocation type is _HOOK_ALLOC or _HOOK_REALLOC,
userData is NULL because the memory block has not been allocated yet.
size specifies the size of the memory block in bytes,
blockType indicates the type of the memory block,
requestNumber is the object allocation order number of the memory block, and, if available,
lineNumber specify the source file name and line number where the triggering allocation operation was initiated.
After the hook function has finished processing, it must return a Boolean value, which tells the main C run-time allocation process how to continue. When the hook function wants the main allocation process to continue as if the hook function had never been called, then the hook function should return TRUE. This causes the original triggering allocation operation to be executed. Using this implementation, the hook function can gather and save allocation information for later analysis, without interfering with the current allocation operation or state of the debug heap.
When the hook function wants the main allocation process to continue as if the triggering allocation operation was called and it failed, then the hook function should return FALSE. Using this implementation, the hook function can simulate a wide range of memory conditions and debug heap states to test how the application handles each situation.
For more information about how _CrtSetAllocHook can be used with other memory management functions or how to write your own client-defined hook functions, see Writing Your Own Debugging Hook Functions.
|_CrtSetAllocHook||<crtdbg.h>||Win 98, Win Me, Win NT, Win 2000, Win XP|
For additional compatibility information, see Compatibility in the Introduction.
Debug versions of C run-time libraries only.
For a sample of how to use _CrtSetAllocHook, see crt_dbg2.