NtQueryDirectoryFileEx - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
#ifndef _NTIOAPI_H
#if (PHNT_VERSION >= PHNT_WINDOWS_10_RS3)

/**
 * The NtQueryDirectoryFileEx routine returns various kinds of information about files in the directory specified by a given file handle.
 *
 * \param[in] FileHandle A handle for the file object that represents the directory for which information is being requested.
 * \param[in] Event An optional handle for a caller-created event. The event is set to the Signaled state the requested operation is completed.
 * \param[in] ApcRoutine An address of an optional, caller-supplied APC routine to be called when the requested operation completes.
 * \param[in] ApcContext An address of an optional, caller-supplied APC or I/O completion object associated with the file object.
 * \param[out] IoStatusBlock A pointer to an IO_STATUS_BLOCK structure that receives the final completion status, and the number of bytes written to the buffer pointed to by FileInformation.
 * \param[out] FileInformation A pointer to a buffer that receives the desired information about the file.
 * \param[in] Length The size, in bytes, of the buffer pointed to by FileInformation.
 * \param[in] FileInformationClass The type of information to be returned about files in the directory.
 * \param[in] QueryFlags One or more of the flags contained in SL_QUERY_DIRECTORY_MASK
 * \param[in] FileName An optional pointer to a Unicode string search expression containing the name of a file (or multiple files, if wildcards are used) within the directory.
 * \return NTSTATUS Successful or errant status.
 * \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntquerydirectoryfileex
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtQueryDirectoryFileEx(
    _In_ HANDLE FileHandle,
    _In_opt_ HANDLE Event,
    _In_opt_ PIO_APC_ROUTINE ApcRoutine,
    _In_opt_ PVOID ApcContext,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _Out_writes_bytes_(Length) PVOID FileInformation,
    _In_ ULONG Length,
    _In_ FILE_INFORMATION_CLASS FileInformationClass,
    _In_ ULONG QueryFlags,
    _In_opt_ PCUNICODE_STRING FileName
    );

#endif
#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwQueryDirectoryFileEx(
    _In_ HANDLE FileHandle,
    _In_opt_ HANDLE Event,
    _In_opt_ PIO_APC_ROUTINE ApcRoutine,
    _In_opt_ PVOID ApcContext,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _Out_writes_bytes_(Length) PVOID FileInformation,
    _In_ ULONG Length,
    _In_ FILE_INFORMATION_CLASS FileInformationClass,
    _In_ ULONG QueryFlags,
    _In_opt_ PCUNICODE_STRING FileName
    );

#endif

View code on GitHub
// ntifs.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFileEx(
  [in]           HANDLE                 FileHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [out]          PIO_STATUS_BLOCK       IoStatusBlock,
  [out]          PVOID                  FileInformation,
  [in]           ULONG                  Length,
                 FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);
View the official Windows Driver Kit DDI reference
// ntifs.h

NTSYSAPI NTSTATUS ZwQueryDirectoryFileEx(
  [in]           HANDLE                 FileHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [out]          PIO_STATUS_BLOCK       IoStatusBlock,
  [out]          PVOID                  FileInformation,
  [in]           ULONG                  Length,
  [in]           FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);
View the official Windows Driver Kit DDI reference

NtDoc

This function is documented in Windows Driver Kit here and here.

Windows Driver Kit DDI reference (nf-ntifs-ntquerydirectoryfileex)

Description

The NtQueryDirectoryFileEx routine returns various kinds of information about files in the directory specified by a given file handle.

Parameters

FileHandle [in]

A handle returned by NtCreateFile or NtOpenFile for the file object that represents the directory for which information is being requested. The file object must have been opened for asynchronous I/O if the caller specifies a non-NULL value for Event or ApcRoutine.

Event [in, optional]

An optional handle for a caller-created event. If this parameter is supplied, the caller will be put into a wait state until the requested operation is completed and the given event is set to the Signaled state. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.

ApcRoutine [in, optional]

An address of an optional, caller-supplied APC routine to be called when the requested operation completes. This parameter is optional and can be NULL. If there is an I/O completion object associated with the file object, this parameter must be NULL.

ApcContext [in, optional]

An optional pointer to a caller-determined context area if the caller supplies an APC or if an I/O completion object is associated with the file object. When the operation completes, this context is passed to the APC, if one was specified, or is included as part of the completion message that the I/O Manager posts to the associated I/O completion object.

This parameter is optional and can be NULL. It must be NULL if ApcRoutine is NULL and there is no I/O completion object associated with the file object.

IoStatusBlock [out]

A pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation. For successful calls that return data, the number of bytes written to the FileInformation buffer is returned in the structure's Information member.

FileInformation [out]

A pointer to an output buffer that receives the desired information about the file. The structure of the information returned in the buffer is defined by the FileInformationClass parameter.

Length [in]

The size, in bytes, of the buffer pointed to by FileInformation. The caller should set this parameter according to the given FileInformationClass.

FileInformationClass

The type of information to be returned about files in the directory. Type of information to be returned about files in the directory. FileInformationClass can be one of the following FILE_INFORMATION_CLASS values.

Value Meaning
FileDirectoryInformation (1) Return a FILE_DIRECTORY_INFORMATION structure for each file.
FileFullDirectoryInformation (2) Return a FILE_FULL_DIR_INFORMATION structure for each file.
FileBothDirectoryInformation (3) Return a FILE_BOTH_DIR_INFORMATION structure for each file.
FileNamesInformation (12) Return a FILE_NAMES_INFORMATION structure for each file.
FileObjectIdInformation (29) Return a FILE_OBJECTID_INFORMATION structure for each file that has an object ID on the volume. This information class is valid only for the special directory "\$Extend\$ObjId:$O:$INDEX_ALLOCATION" on NTFS volumes.
FileQuotaInformation (32) Return a single FILE_QUOTA_INFORMATION structure for each user on the volume that has quotas applied. This information class is valid only for the special directory "\$Extend\$Quota:$Q:$INDEX_ALLOCATION" on NTFS volumes.
FileReparsePointInformation (33) Return a single FILE_REPARSE_POINT_INFORMATION structure for each file that has a reparse point on the volume. This information class is valid only for the special directory "\$Extend\$Reparse:$R:$INDEX_ALLOCATION" on NTFS and ReFS volumes.
FileIdBothDirectoryInformation (37) Return a FILE_ID_BOTH_DIR_INFORMATION structure for each file.
FileIdFullDirectoryInformation (38) Return a FILE_ID_FULL_DIR_INFORMATION structure for each file.
FileIdGlobalTxDirectoryInformation (50) Return a FILE_ID_GLOBAL_TX_DIR_INFORMATION structure for each file.
FileIdExtdDirectoryInformation (60) Return a FILE_ID_EXTD_DIR_INFORMATION structure for each file.
FileIdExtdBothDirectoryInformation (63) Return a FILE_ID_EXTD_BOTH_DIR_INFORMATION structure for each file.

QueryFlags [in]

One or more of the flags contained in SL_QUERY_DIRECTORY_MASK. Possible values are specified in the following table.

Value Meaning
SL_RESTART_SCAN (0x00000001) The scan will start at the first entry in the directory. If this flag is not set, the scan will resume from where the last query ended.
SL_RETURN_SINGLE_ENTRY (0x00000002) Normally the return buffer is packed with as many matching directory entries that fit. If this flag is set, the file system will return only one directory entry at a time. This does make the operation less efficient.
SL_INDEX_SPECIFIED (0x00000004) The scan should start at a specified indexed position in the directory. This flag can only be set if you generate your own IRP_MJ_DIRECTORY_CONTROL IRP; the index is specified in the IRP. How the position is specified varies from file system to file system.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008) Any file system filters that perform directory virtualization or just-in-time expansion should simply pass the request through to the file system and return entries that are currently on disk. Not all file systems support this flag.
SL_NO_CURSOR_UPDATE_QUERY (0x00000010) File systems maintain per-FileObject directory cursor information. When multiple threads do queries using the same FileObject, access to the per-FileObject structure is single threaded to prevent corruption of the cursor state. This flag tells the file system to not update per-FileObject cursor state information thus allowing multiple threads to query in parallel using the same handle. It behaves as if SL_RESTART_SCAN is specified on each call. If a wild card pattern is given on the next call, the operation will not pick up where the last query ended. This allows for true asynchronous directory query support. If this flag is used inside a TxF transaction the operation will be failed. Not all file systems support this flag.

FileName [in, optional]

An optional pointer to a caller-allocated Unicode string containing the name of a file (or multiple files, if wildcards are used) within the directory specified by FileHandle. This parameter is optional:

The FileName is used as a search expression and is captured on the very first call to NtQueryDirectoryFileEx for a given handle. Subsequent calls to NtQueryDirectoryFileEx will use the search expression set in the first call. The FileName parameter passed to subsequent calls will be ignored.

Return value

NtQueryDirectoryFileEx returns STATUS_SUCCESS or an appropriate error status. The set of error status values that can be returned is file system-specific. NtQueryDirectoryFileEx also returns the number of bytes actually written to the given FileInformation buffer in the Information member of IoStatusBlock. Some possible error codes and reasons might be the following:

Return code Meaning
STATUS_BUFFER_OVERFLOW The output buffer isn't large enough to return the full filename.
STATUS_BUFFER_TOO_SMALL The output buffer isn't large enough for at least the base structure identified by FileInformationClass.
STATUS_INVALID_INFO_CLASS An invalid FileInformationClass was specified, or the information class is valid only for a special condition (for example, valid only for a special directory).
STATUS_INVALID_PARAMETER One of the parameters is invalid for the file system.

Remarks

NtQueryDirectoryFileEx returns information about files that are contained in the directory represented by FileHandle.

If provided, FileName determines the entries that are included in the directory scan for all subsequent calls to NtQueryDirectoryFileEx for a given FileHandle.

If there is at least one matching entry, NtQueryDirectoryFileEx creates a FILE_XXX_INFORMATION structure for each entry and stores them in the buffer.

Assuming that at least one matching directory entry is found, the number of entries for which information is returned is the smallest of the following:

On the first call to NtQueryDirectoryFileEx, if the structure it creates for the first entry found is too large to fit into the output buffer, this routine does the following:

On each call, NtQueryDirectoryFileEx returns as many FILE_XXX_INFORMATION structures (one per directory entry) as can be contained entirely in the buffer pointed to by FileInformation:

When calling NtQueryDirectoryFileEx, you might see changes made to the directory that occur in parallel with NtQueryDirectoryFileEx calls. This behavior is dependent on the implementation of the underlying file system.

The final call to NtQueryDirectoryFileEx returns an empty output buffer and reports an appropriate status value such as STATUS_NO_MORE_FILES.

If NtQueryDirectoryFileEx is called multiple times on the same directory and some other operation changes the contents of that directory, any changes might or might not be seen, depending on the timing of the operations.

NtQueryDirectoryFileEx returns zero in any member of a FILE_XXX_INFORMATION structure that is not supported by the file system.

Callers of NtQueryDirectoryFileEx must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

For information about other file information query routines, see File Objects.

[!NOTE] If the call to the NtQueryDirectoryFileEx function occurs in kernel mode, you should use the name "ZwQueryDirectoryFileEx" instead of "NtQueryDirectoryFileEx".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

FILE_BOTH_DIR_INFORMATION

FILE_DIRECTORY_INFORMATION

FILE_FULL_DIR_INFORMATION

FILE_ID_BOTH_DIR_INFORMATION

FILE_ID_FULL_DIR_INFORMATION

FILE_NAMES_INFORMATION

FILE_OBJECTID_INFORMATION

FILE_REPARSE_POINT_INFORMATION

UNICODE_STRING

Using Nt and Zw Versions of the Native System Services Routines

ZwCreateFile

ZwOpenFile


Windows Driver Kit DDI reference (nf-ntifs-zwquerydirectoryfileex)

Description

The ZwQueryDirectoryFileEx routine returns various information about files in the directory specified by a given file handle.

Parameters

FileHandle [in]

A handle returned by ZwCreateFile or ZwOpenFile for the file object that represents the directory for which information is being requested. The file object must have been opened for asynchronous I/O if the caller specifies a non-NULL value for Event or ApcRoutine.

Event [in, optional]

An optional handle for a caller-created event. If this parameter is supplied, the caller will be put into a wait state until the requested operation is completed and the given event is set to the Signaled state. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.

ApcRoutine [in, optional]

An address of an optional, caller-supplied APC routine to be called when the requested operation completes. This parameter is optional and can be NULL. If there is an I/O completion object associated with the file object, this parameter must be NULL.

ApcContext [in, optional]

An optional pointer to a caller-determined context area if the caller supplies an APC or if an I/O completion object is associated with the file object. When the operation completes, this context is passed to the APC, if one was specified, or is included as part of the completion message that the I/O Manager posts to the associated I/O completion object.

This parameter is optional and can be NULL. It must be NULL if ApcRoutine is NULL and there is no I/O completion object associated with the file object.

IoStatusBlock [out]

A pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation. For successful calls that return data, the number of bytes written to the FileInformation buffer is returned in the structure's Information member.

FileInformation [out]

A pointer to an output buffer that receives the desired information about the file. The structure of the information returned in the buffer is defined by the FileInformationClass parameter.

Length [in]

The size, in bytes, of the buffer pointed to by FileInformation. The caller should set this parameter according to the given FileInformationClass.

FileInformationClass [in]

The type of information to be returned about files in the directory. See the FileInformationClass parameter of NtQueryDirectoryFileEx for the list of possible values.

QueryFlags [in]

One or more of the flags contained in SL_QUERY_DIRECTORY_MASK. See the QueryFlags parameter of NtQueryDirectoryFileEx for the list of possible values.

FileName [in, optional]

An optional pointer to a caller-allocated Unicode string containing the name of a file (or multiple files, if wildcards are used) within the directory specified by FileHandle. This parameter is optional:

The FileName is used as a search expression and is captured on the very first call to ZwQueryDirectoryFileEx for a given handle. Subsequent calls to ZwQueryDirectoryFileEx will use the search expression set in the first call. The FileName parameter passed to subsequent calls will be ignored.

Return value

ZwQueryDirectoryFileEx returns STATUS_SUCCESS or an appropriate error status. The set of error status values that can be returned is file system-specific. ZwQueryDirectoryFileEx also returns the number of bytes actually written to the given FileInformation buffer in the Information member of IoStatusBlock. See NtQueryDirectoryFileEx for a list of some possible error codes.

Remarks

ZwQueryDirectoryFileEx returns information about files that are contained in the directory represented by FileHandle.

If provided, FileName determines the entries that are included in the directory scan for all subsequent calls to ZwQueryDirectoryFileEx for a given FileHandle.

If there is at least one matching entry, ZwQueryDirectoryFileEx creates a FILE_XXX_INFORMATION structure for each entry and stores them in the buffer.

Assuming that at least one matching directory entry is found, the number of entries for which information is returned is the smallest of the following:

On the first call to ZwQueryDirectoryFileEx, if the structure it creates for the first entry found is too large to fit into the output buffer, this routine does the following:

On each call, ZwQueryDirectoryFileEx returns as many FILE_XXX_INFORMATION structures (one per directory entry) as can be contained entirely in the buffer pointed to by FileInformation:

When calling ZwQueryDirectoryFileEx, you might see changes made to the directory that occur in parallel with ZwQueryDirectoryFileEx calls. This behavior is dependent on the implementation of the underlying file system.

The final call to ZwQueryDirectoryFileEx returns an empty output buffer and reports an appropriate status value such as STATUS_NO_MORE_FILES.

If ZwQueryDirectoryFileEx is called multiple times on the same directory and some other operation changes the contents of that directory, any changes might or might not be seen, depending on the timing of the operations.

ZwQueryDirectoryFileEx returns zero in any member of a FILE_XXX_INFORMATION structure that is not supported by the file system.

Callers of ZwQueryDirectoryFileEx must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

For information about other file information query routines, see File Objects.

[!NOTE] If the call to the ZwQueryDirectoryFileEx function occurs in user mode, you should use the name "NtQueryDirectoryFileEx" instead of "ZwQueryDirectoryFileEx".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

FILE_BOTH_DIR_INFORMATION

FILE_DIRECTORY_INFORMATION

FILE_FULL_DIR_INFORMATION

FILE_ID_BOTH_DIR_INFORMATION

FILE_ID_FULL_DIR_INFORMATION

FILE_NAMES_INFORMATION

FILE_OBJECTID_INFORMATION

FILE_REPARSE_POINT_INFORMATION

UNICODE_STRING

Using Nt and Zw Versions of the Native System Services Routines

ZwCreateFile

ZwOpenFile