ExAllocatePoolWithTag

PVOID
ExAllocatePoolWithTag(
IN POOL_TYPE PoolType,
IN ULONG NumberOfBytes,
IN ULONG Tag
);

ExAllocatePoolWithTag allocates pool memory. A call to this routine is equivalent to calling ExAllocatePool, except it inserts a caller-supplied tag before the allocation. This tag appears in any crash dump of the system that occurs.

Parameters

PoolType: Specifies the type of pool memory to allocate, which can be one of the following:
NonPagedPool
NonPagedPoolMustSucceed
NonPagedPoolCacheAligned
NonPagedPoolCacheAlignedMustS
PagedPool
PagedPoolCacheAligned
NumberOfBytes: Specifies the number of bytes to allocate.
Tag: Is a string, delimited by single quote marks, with up to four characters, usually specified in reversed order.

Return Value

If the PoolType is one of the XxxMustS(ucceed) values, this call succeeds if the system has any available memory, and ExAllocatePoolWithTag returns a pointer to allocated pool memory.

ExAllocatePoolWithTag returns a NULL pointer if the PoolType is not one of the XxxMustS(ucceed) values and not enough free pool exists to satisfy the request.

Comments

During driver development on a checked build of the system, this routine can be useful for crash debugging. Calling this routine, rather than ExAllocatePool, inserts the caller-supplied tag into a crash dump of pool memory.

The Tag passed to this routine is more readable if its bytes are reversed when this routine is called. For example, if a caller passes ‘Fred’ as a Tag, it would appear as ‘derF’ if pool is dumped or when tracking pool usage in the debugger.

Callers of ExAllocatePoolWithTag, like callers of ExAllocatePool, can be running at IRQL DISPATCH_LEVEL only if the requested PoolType is one of the NonPagedXxx. Otherwise, callers must be running at IRQL < DISPATCH_LEVEL.