ZwQueryDirectoryFile function

Description

The ZwQueryDirectoryFile 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.

ReturnSingleEntry [in]

Set to TRUE if only a single entry should be returned, FALSE otherwise. If this parameter is TRUE, ZwQueryDirectoryFile returns only the first entry that is found.

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:

• If FileName is not NULL, only files whose names match the FileName string are included in the directory scan.
• If FileName is NULL, all files are included if ReturnSingleEntry is FALSE; one file is included if ReturnSingleEntry is TRUE.

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

RestartScan [in]

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.

When the ZwQueryDirectoryFile routine is called for a particular handle, the RestartScan parameter is treated as if it were set to TRUE, regardless of its value. On subsequent ZwQueryDirectoryFile calls, the value of the RestartScan parameter is honored.

Return value

The ZwQueryDirectoryFile routine returns STATUS_SUCCESS or an appropriate error status. The set of error status values that can be returned is file system-specific. ZwQueryDirectoryFile 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

The ZwQueryDirectoryFile routine 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 ZwQueryDirectoryFile for a given FileHandle.

If there is at least one matching entry, ZwQueryDirectoryFile 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:

• One entry, if ReturnSingleEntry is TRUE and FileName is NULL.
• The number of entries that match the FileName string, if FileName is not NULL. If the string contains no wildcards, there can be at most one matching entry.
• The number of entries whose information fits into the specified buffer.
• The number of entries contained in the directory.

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

• Writes the fixed portion of the structure to FileInformation's output buffer. The fixed portion consists of all fields except the final FileName string. On the first call, but not on subsequent calls, the I/O system ensures that the buffer is large enough to hold the fixed portion of the appropriate FILE_XXX_INFORMATION structure.
• Writes to the output buffer as much of the FileName string as will fit.
• Returns an appropriate status value such as STATUS_BUFFER_OVERFLOW.

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

• On the first call, ZwQueryDirectoryFile returns STATUS_SUCCESS only if the output buffer contains at least one complete structure.
• On subsequent calls, if the output buffer contains no structures, ZwQueryDirectoryFile returns STATUS_SUCCESS but sets IoStatusBlock->Information = 0 to notify the caller of this condition. In this case, the caller should allocate a larger buffer and call ZwQueryDirectoryFile again. No information about any remaining entries is reported. Thus, except in the cases listed above where only one entry is returned, ZwQueryDirectoryFile must be called at least twice to enumerate the contents of an entire directory.

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

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

If ZwQueryDirectoryFile 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.

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

Callers of ZwQueryDirectoryFile 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 ZwQueryDirectoryFile function occurs in user mode, you should use the name "NtQueryDirectoryFile" instead of "ZwQueryDirectoryFile".

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

ZwQueryDirectoryFileEx

ZwOpenFile

---

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:

• STATUS_SUCCESS - Enumeration has results in FileInformation buffer.
• STATUS_NO_MORE_FILES - FileInformation buffer is empty, and next call isn't needed.
• STATUS_NO_SUCH_FILE - Returned when FileMask parameter specify exactly one file (don't contains '*' or '?' characters), and queried directory don't contains that file.

FileInformation

User's allocated buffer for output data.

Length

Length of FileInformation buffer, in bytes.

FileInformationClass

Information class. Can be one of:

• FileDirectoryInformation
• FileFullDirectoryInformation
• FileBothDirectoryInformation
• FileNamesInformation
• FileOleDirectoryInformation

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

• Tomasz Nowak
• Bo Branten

See also

• NtCreateFile
• NtOpenFile
• NtQueryInformationFile
• NtQueryOleDirectoryFile
• NtQueryVolumeInformationFile