Export (0) Print
Expand All
Expand Minimize

FltAllocatePoolAlignedWithTag function

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

Syntax


PVOID FltAllocatePoolAlignedWithTag(
  _In_  PFLT_INSTANCE Instance,
  _In_  POOL_TYPE PoolType,
  _In_  SIZE_T NumberOfBytes,
  _In_  ULONG Tag
);

Parameters

Instance [in]

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

PoolType [in]

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.

NumberOfBytes [in]

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

Tag [in]

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

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

IRQL

<= APC_LEVEL (see Remarks section)

See also

ExAllocatePoolWithTag
FltFreePoolAlignedWithTag
FltReadFile
FltWriteFile

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft