ZwQueryEaFile function (ntifs.h)

Article
04/26/2024

ZwQueryEaFile routine returns the extended attributes (EAs) associated with the specified file.

Syntax

NTSTATUS ZwQueryEaFile(
  [in]           HANDLE           FileHandle,
  [out]          PIO_STATUS_BLOCK IoStatusBlock,
  [out]          PVOID            Buffer,
  [in]           ULONG            Length,
  [in]           BOOLEAN          ReturnSingleEntry,
  [in, optional] PVOID            EaList,
  [in]           ULONG            EaListLength,
  [in, optional] PULONG           EaIndex,
  [in]           BOOLEAN          RestartScan
);

Parameters

[in] FileHandle

The handle for the file on which the operation is to be performed.

[out] IoStatusBlock

A pointer to an IO_STATUS_BLOCK structure that receives the final completion status and other information about the requested operation.

[out] Buffer

A pointer to a caller-supplied FILE_FULL_EA_INFORMATION-structured output buffer in which to return the file's EAs.

[in] Length

The length, in bytes, of the buffer that Buffer points to.

[in] ReturnSingleEntry

Set to TRUE if ZwQueryEaFile should return only the first entry that it finds.

[in, optional] EaList

A pointer to a caller-supplied FILE_GET_EA_INFORMATION-structured input buffer that specifies the EAs to be queried. This parameter is optional and can be NULL.

[in] EaListLength

The length, in bytes, of the buffer that the EaList parameter points to.

[in, optional] EaIndex

The index of the entry at which scanning the file's EA list should begin. This parameter is ignored if EaList points to a nonempty list. This parameter is optional and can be NULL.

[in] RestartScan

Set to TRUE if ZwQueryEaFile should begin the scan at the first entry in the file's EA list. If this parameter is set to FALSE, the routine resumes the scan from a previous call to ZwQueryEaFile.

Return value

ZwQueryEaFile returns STATUS_SUCCESS or an appropriate NTSTATUS value such as the following:

Return value	Description
STATUS_EAS_NOT_SUPPORTED	The file system doesn't support EAs. This is an error code.
STATUS_INSUFFICIENT_RESOURCES	There isn't enough memory available to complete the operation. This is an error code.
STATUS_EA_LIST_INCONSISTENT	The EaList parameter isn't formatted correctly. This is an error code.

Remarks

The amount of information that ZwQueryEaFile returns is based on the size of the EAs and the size of the buffer that Buffer points to. That is, either all of the requested EAs are written to the buffer, or the buffer is filled with as many complete EAs if it's not large enough to contain all the EAs. Only complete EAs are written to the buffer; no partial EAs will ever be returned.

Requirements

Requirement	Value
Minimum supported client	Windows 2000
Target Platform	Universal
Header	ntifs.h (include FltKernel.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI compliance rules	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)