ExAllocatePoolWithTag

The ExAllocatePoolWithTag routine allocates pool memory of the specified type, and returns a pointer to the allocated block.

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

Parameters

PoolType

Specifies the type of pool memory to allocate. For a description of the available pool memory types, see POOL_TYPE.

NumberOfBytes

Specifies the number of bytes to allocate.

Tag

Specifies the pool tag for the allocated memory. Drivers normally specify the pool tag as a string of up to four characters, delimited by single quotation marks. The string is usually specified in reversed order. The ASCII value of each character in the tag must be between 0 and 127.

Return Value

ExAllocatePoolWithTag returns NULL if there is insufficient memory in the free pool to satisfy the request. Otherwise, the routine returns a pointer to the allocated memory.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

This routine is used for the general pool allocation of memory.

If NumberOfBytes is PAGE_SIZE or greater, a page-aligned buffer is allocated. Memory allocations of PAGE_SIZE or less do not cross page boundaries. Memory allocations of less than PAGE_SIZE are not necessarily page-aligned but are aligned on an 8-byte boundary.

A successful allocation requesting NumberOfBytes < PAGE_SIZE of nonpaged pool gives the caller exactly the number of requested bytes of memory. Any successful allocation that requests NumberOfBytes > PAGE_SIZE wastes all unused bytes on the last-allocated page.

The system associates the pool tag with the allocated memory. Programming tools, such as WinDbg, can display the pool tag associated with each allocated buffer. The value of Tag is normally displayed in reversed order. 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.

The allocated buffer can be freed with either ExFreePool or ExFreePoolWithTag.

The system automatically sets certain standard event objects when the amount of pool (paged or nonpaged) is high or low. Drivers can wait for these events to tune their pool usage. For more information, see Standard Event Objects.

Callers of ExAllocatePoolWithTag must be executing at IRQL <= DISPATCH_LEVEL. A caller executing at DISPATCH_LEVEL must specify a NonPagedXxx value for PoolType. A caller executing at IRQL < DISPATCH_LEVEL can specify any POOL_TYPE value.

See Also

ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority, ExFreePool, ExFreePoolWithTag