_CrtIsMemoryBlock

Verifies that a specified memory block is in the local heap and that it has a valid debug heap block type identifier (debug version only).

int_CrtIsMemoryBlock(constvoid *userData**,unsignedintsize,long****requestNumber***,char** **filename**,int****linenumber***);**

Routine	Required Header	Compatibility
_CrtIsMemoryBlock	<crtdbg.h>	Win NT, Win 95

For additional compatibility information, see Compatibility in the Introduction.

Libraries

LIBCD.LIB	Single thread static library, debug version
LIBCMTD.LIB	Multithread static library, debug version
MSVCRTD.LIB	Import library for MSVCRTD.DLL, debug version

Return Value

_CrtIsMemoryBlock returns TRUE if the specified memory block is located within the local heap and has a valid debug heap block type identifier; otherwise, the function returns FALSE.

Parameter

userData

Pointer to the beginning of the memory block to verify

size

Size of the specified block (bytes)

requestNumber

Pointer to the allocation number of the block or NULL

filename

Pointer to name of source file that requested the block or NULL

linenumber

Pointer to the line number in the source file or NULL

Remarks

The _CrtIsMemoryBlock function verifies that a specified memory block is located within the application’s local heap and that it has a valid block type identifier. This function can also be used to obtain the object allocation order number and source file name/line number where the memory block allocation was originally requested. Passing non-NULL values for the requestNumber, filename, and/or linenumber parameters causes _CrtIsMemoryBlock to set these parameters to the values in the memory block’s debug header, if it finds the block in the local heap. When _DEBUG is not defined, calls to _CrtIsMemoryBlock are removed during preprocessing.

Because this function returns TRUE or FALSE, it can be passed to one of the _ASSERT macros to create a simple debugging error handling mechanism. The following example will cause an assertion failure if the specified address is not located within the local heap:

_ASSERTE( _CrtIsMemoryBlock( userData, size, &requestNumber, &filename, &linenumber ) );

For more information about how _CrtIsMemoryBlock can be used with other debug functions and macros, see Using Macros for Verification and Reporting. For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see Memory Management and the Debug Heap.

Example

/*
 * ISVALID.C
 * This program allocates a block of memory using _malloc_dbg
 * and then tests the validity of this memory by calling _CrtIsMemoryBlock,
 * _CrtIsValidPointer, and _CrtIsValidHeapPointer.
 */

#include <stdio.h>
#include <string.h>
#include <malloc.h>
#include <crtdbg.h>

#define  TRUE   1
#define  FALSE  0

void main( void )
{
        char *my_pointer;

        /*
         * Call _malloc_dbg to include the filename and line number
         * of our allocation request in the header information
         */
        my_pointer = (char *)_malloc_dbg( sizeof(char) * 10, _NORMAL_BLOCK, __FILE__, __LINE__ );

        /*
         * Ensure that the memory got allocated correctly
         */
        _CrtIsMemoryBlock((const void *)my_pointer, sizeof(char) * 10, NULL, NULL, NULL );

        /*
         * Test for read/write accessibility
         */
        if (_CrtIsValidPointer((const void *)my_pointer, sizeof(char) * 10, TRUE))
                printf("my_pointer has read and write accessibility.\n");
        else
                printf("my_pointer only has read access.\n");

        /*
         * Make sure my_pointer is within the local heap
         */
        if (_CrtIsValidHeapPointer((const void *)my_pointer))
                printf("my_pointer is within the local heap.\n");
        else
                printf("my_pointer is not located within the local heap.\n");

        free(my_pointer);
}

Output

my_pointer has read and write accessibility.
my_pointer is within the local heap.

Debug Functions