NtQueryDirectoryFile - NtDoc

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

/**
 * The NtQueryDirectoryFile 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] ReturnSingleEntry Set to TRUE if only a single entry should be returned, FALSE otherwise.
 * \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.
 * \param[in] RestartScan Set to TRUE if the scan is to start at the first entry in the directory. Set to FALSE if resuming the scan from a previous call.
 * \return NTSTATUS Successful or errant status.
 * \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntquerydirectoryfile
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtQueryDirectoryFile(
    _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_ BOOLEAN ReturnSingleEntry,
    _In_opt_ PCUNICODE_STRING FileName,
    _In_ BOOLEAN RestartScan
    );

#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwQueryDirectoryFile(
    _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_ BOOLEAN ReturnSingleEntry,
    _In_opt_ PCUNICODE_STRING FileName,
    _In_ BOOLEAN RestartScan
    );

#endif

View code on GitHub

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


NtQueryDirectoryFile is used to enumerate entries (files or directories) placed into file container object (directory). Win32 API use it in FindFirstFile-FindNextFile routines.

FileHandle

HANDLE to File Object opened with FILE_DIRECTORY_FILE option and FILE_LIST_DIRECTORY access.

Event

Optional HANDLE to Event Object signaled after query complete.

ApcRoutine

Optional pointer to user's APC routine queued after query complete.

ApcContext

Parameter for ApcRoutine.

IoStatusBlock

Pointer to IO_STATUS_BLOCK structure. After enumeration complete, Information member of this structure contains number of bytes written into FileInformation buffer. Status member contains IO result of call, and can be one of:

FileInformation

User's allocated buffer for output data.

Length

Length of FileInformation buffer, in bytes.

FileInformationClass

Information class. Can be one of:

ReturnSingleEntry

If set, only one entry is returned.

FileMask

If specified, only information about files matches this wildchar mask will be returned.

WARNING: There's no rule specifying what to do when caller makes two calls to NtQueryDirectoryFile both with different masks. Typically FileMask specified in second call will be ignored, and results will match the first (for example: NTFS.SYS). The best solution is to close directory HANDLE after every call with FileMask parameter specified.

RestartScan

Used with ReturnSingleEntry parameter. If set, NtQueryDirectoryFile continue enumeration after last enumerated element in previous call. If no, returns the first entry in directory.


For detailed information about results, see FILE_INFORMATION_CLASS with information classes specified above.

Documented by

See also