Allocation Hook Functions
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

Allocation Hook Functions 

This topic applies to:

Visual Studio Edition

Visual Basic

C#

C++

J#

Express Edition

No

No

Native

No

Standard Edition

No

No

Native

No

Pro/Team Edition

No

No

Native

No

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.

NoteNote

Be aware of the restriction about using C run-time library functions in an allocation hook function, described in Allocation Hooks and C Run-Time Memory Allocations.

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 unsigned 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.

See Also

Show:
© 2016 Microsoft