FsRtlAllocateExtraCreateParameterList function (ntifs.h)

Article
09/27/2023

The FsRtlAllocateExtraCreateParameterList routine allocates paged pool memory for an ECP_LIST structure and generates a pointer to that structure.

Syntax

NTSTATUS FsRtlAllocateExtraCreateParameterList(
  [in]  FSRTL_ALLOCATE_ECPLIST_FLAGS Flags,
  [out] PECP_LIST                    *EcpList
);

Parameters

[in] Flags

Defines pool allocation options. If the FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA flag is combined with the Flags parameter by using a bitwise OR operation, any pool allocated by FsRtlAllocateExtraCreateParameterList will be charged against the current process' memory quota.

[out] EcpList

Receives a pointer to an initialized ECP list structure. If FsRtlAllocateExtraCreateParameterList failed to allocate sufficient pool, *EcpList will be NULL and FsRtlAllocateExtraCreateParameterList will return status code STATUS_INSUFFICIENT_RESOURCES.

Return value

FsRtlAllocateExtraCreateParameterList can return one of the following values:

Return code	Description
STATUS_INSUFFICIENT_RESOURCES	FsRtlAllocateExtraCreateParameterList was unable to allocate sufficient memory for an ECP list structure. In this case, *EcpList will be NULL.
STATUS_SUCCESS	The memory for the ECP_LIST structure was successfully allocated and initialized. In this case, a pointer to the initialized list structure is returned in the EcpList parameter.

Remarks

Whether the operating system automatically frees memory that FsRtlAllocateExtraCreateParameterList allocates depends on when FsRtlAllocateExtraCreateParameterList is called, as shown in the following situations:

A caller can invoke FsRtlAllocateExtraCreateParameterList to allocate the ECP_LIST and add one or more ECP context structures before the caller invokes the IoCreateFileEx routine. In this situation, the operating system does not free any of the ECP context structures. Therefore, the caller can make multiple calls to IoCreateFileEx with the same ECP set. When the caller is done with the ECP_LIST, the caller must call the FltFreeExtraCreateParameter routine to free the ECP_LIST.
While a file system or file system filter driver processes an IRP_MJ_CREATE request, the file system or file system filter driver can call FltInsertExtraCreateParameter to attach an ECP to an existing ECP_LIST. If the ECP_LIST does not exist, the caller must call FsRtlAllocateExtraCreateParameterList to create the ECP_LIST. In this situation, the ECP_LIST and the ECP context structure are automatically cleaned up by the I/O manager when the create operation completes. This allows a file system's or filter driver's ECP to be properly propagated across the processing of reparse points. This process might require multiple IRP_MJ_CREATE requests to be generated.

If the FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA flag is used with the Flags parameter, a pageable pool is allocated. Otherwise, a pageable pool is allocated by using an internal lookaside list.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Target Platform	Universal
Header	ntifs.h (include Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL