NtQueryInformationFile function (ntifs.h)

The NtQueryInformationFile routine returns various kinds of information about a file object. See also NtQueryInformationByName, which can be more efficiently used for a few file information classes.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Parameters

[in] FileHandle

Handle to a file object. The handle is created by a successful call to NtCreateFile or NtOpenFile, or to an equivalent file create or open routine.

[out] IoStatusBlock

Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation. The Information member receives the number of bytes that this routine actually writes to the FileInformation buffer.

[out] FileInformation

Pointer to a caller-allocated buffer into which the routine writes the requested information about the file object. The FileInformationClass parameter specifies the type of information that the caller requests.

[in] Length

The size, in bytes, of the buffer pointed to by FileInformation.

[in] FileInformationClass

Specifies the type of information to be returned about the file, in the buffer that FileInformation points to. Device and intermediate drivers can specify any of the following FILE_INFORMATION_CLASS values (listed from lowest to highest enum value):

Return value

NtQueryInformationFile returns STATUS_SUCCESS or an appropriate NTSTATUS error code.

Remarks

NtQueryInformationFile returns information about the specified file object. Note that it returns zero in any member of a FILE_XXX_INFORMATION structure that is not supported by a particular device or file system.

When FileInformationClass = FileNameInformation, the file name is returned in the FILE_NAME_INFORMATION structure. The precise syntax of the file name depends on a number of factors:

• If you opened the file by submitting a full path to NtCreateFile, NtQueryInformationFile returns that full path.

• If the ObjectAttributes->RootDirectory handle was opened by name in a call to NtCreateFile, and subsequently the file was opened by NtCreateFile relative to this root-directory handle, NtQueryInformationFile returns the full path.

• If the ObjectAttributes->RootDirectory handle was opened by file ID (using the FILE_OPEN_BY_FILE_ID flag) in a call to NtCreateFile, and subsequently the file was opened by NtCreateFile relative to this root-directory handle, NtQueryInformationFile returns the relative path.

• However, if the user has SeChangeNotifyPrivilege (described in the Microsoft Windows SDK documentation), NtQueryInformationFile returns the full path in all cases.

• If only the relative path is returned, the file name string will not begin with a backslash.

• If the full path and file name are returned, the string will begin with a single backslash, regardless of its location. Thus the file C:\dir1\dir2\filename.ext will appear as \dir1\dir2\filename.ext, while the file \server\share\dir1\dir2\filename.ext will appear as \server\share\dir1\dir2\filename.ext.

If NtQueryInformationFile fails because of a buffer overflow, drivers that implement FileNameInformation should return as many WCHAR characters of the file name as will fit in the buffer and specify the full length that is required in the FileNameLength parameter of the FILE_NAME_INFORMATION structure. You should reissue the query by using the file name length so that you can retrieve the full file name. Drivers that do not follow this pattern might require a gradual increase in length until they retrieve the full file name. For more information about working with files, see Using Files in a Driver.

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

For calls from kernel-mode drivers, the NtXxx and ZwXxx 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 NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

Requirements

See also

FILE_ACCESS_INFORMATION

FILE_ALIGNMENT_INFORMATION

FILE_ALL_INFORMATION

FILE_ATTRIBUTE_TAG_INFORMATION

FILE_BASIC_INFORMATION

FILE_EA_INFORMATION

FILE_INTERNAL_INFORMATION

FILE_IO_PRIORITY_HINT_INFORMATION

FILE_IS_REMOTE_DEVICE_INFORMATION

FILE_MODE_INFORMATION

FILE_NAME_INFORMATION

FILE_NETWORK_OPEN_INFORMATION

FILE_POSITION_INFORMATION

FILE_STANDARD_INFORMATION

Using Nt and Zw Versions of the Native System Services Routines

NtCreateFile

NtQueryInformationByName

NtSetInformationFile