FltAllocatePoolAlignedWithTag function (fltkernel.h)

FltAllocatePoolAlignedWithTag allocates a device-aligned buffer for use in a noncached I/O operation.

Syntax

PVOID FLTAPI FltAllocatePoolAlignedWithTag(
  [in] PFLT_INSTANCE Instance,
  [in] POOL_TYPE     PoolType,
  [in] SIZE_T        NumberOfBytes,
  [in] ULONG         Tag
);

Parameters

[in] Instance

Opaque instance pointer for a caller-owned minifilter driver instance that is attached to the volume. This parameter is required and cannot be NULL.

[in] PoolType

Type of pool to allocate. One of the following:

NonPagedPool

PagedPool

NonPagedPoolCacheAligned

PagedPoolCacheAligned

See POOL_TYPE for a description of the available pool memory types.

[in] NumberOfBytes

Number of bytes to allocate. This parameter is required and can be zero.

[in] Tag

Specifies the pool tag for the allocated memory. Drivers normally specify the pool tag as a string of one to four 7-bit ASCII characters, delimited by single quotation marks (for example, 'abcd'). This parameter is required and cannot be zero.

Return value

If not enough free pool is available to satisfy the request, FltAllocatePoolAlignedWithTag returns a NULL pointer. Otherwise, FltAllocatePoolAlignedWithTag returns a pointer to the newly allocated buffer.

Remarks

FltAllocatePoolAlignedWithTag allocates a buffer that is aligned in accordance with the underlying device for the given volume. Such device-aligned buffers are required for noncached I/O. (They can also be used for cached I/O.) Thus when calling routines that perform noncached I/O, such as FltReadFile and FltWriteFile, minifilter drivers should call FltAllocatePoolAlignedWithTag instead of ExAllocatePoolWithTag.

If the caller specifies a value of zero for the NumberOfBytes parameter, FltAllocatePoolAlignedWithTag allocates the smallest amount of memory that meets the alignment requirement.

The system associates the pool tag specified by the Tag parameter with the allocated buffer. Programming tools, such as the Windows Debugger (WinDbg), can display the pool tag associated with each allocated buffer. The value of the pool tag is normally displayed in reversed order. For example, if a caller passes 'Fred' as the value of the Tag parameter, this value would appear as 'derF' if pool is dumped or when tracking pool usage in the debugger.

For more information about memory management, see Memory Management.

When the buffer that FltAllocatePoolAlignedWithTag allocates is no longer needed, the caller is responsible for freeing it by calling FltFreePoolAlignedWithTag.

Callers of FltAllocatePoolAlignedWithTag can be running at IRQL DISPATCH_LEVEL only if a NonPagedXxxPoolType is specified. Otherwise, callers must be running at IRQL <= APC_LEVEL.

Requirements

See also

ExAllocatePoolWithTag

FltFreePoolAlignedWithTag

FltReadFile

FltWriteFile