ZwQueryInformationFile routine

The ZwQueryInformationFile routine returns various kinds of information about a file object.

Syntax


NTSTATUS ZwQueryInformationFile(
  _In_   HANDLE FileHandle,
  _Out_  PIO_STATUS_BLOCK IoStatusBlock,
  _Out_  PVOID FileInformation,
  _In_   ULONG Length,
  _In_   FILE_INFORMATION_CLASS FileInformationClass
);

Parameters

FileHandle [in]

Handle to a file object. The handle is created by a successful call to ZwCreateFile or ZwOpenFile.

IoStatusBlock [out]

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.

FileInformation [out]

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.

Length [in]

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

FileInformationClass [in]

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.

FILE_INFORMATION_CLASS valueType of information returned

FileAccessInformation

A FILE_ACCESS_INFORMATION structure. This structure contains an access mask. For more information about access masks, see ACCESS_MASK.

FileAlignmentInformation

A FILE_ALIGNMENT_INFORMATION structure. The caller can query this information as long as the file is open, without any particular requirements for DesiredAccess. This information is useful if the file was opened with the FILE_NO_INTERMEDIATE_BUFFERING flag specified in the CreateOptions parameter.

FileAllInformation

A FILE_ALL_INFORMATION structure. By combining several file-information structures into a single structure, FILE_ALL_INFORMATION reduces the number of queries required to obtain information about a file.

FileAttributeTagInformation

A FILE_ATTRIBUTE_TAG_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter.

FileBasicInformation

A FILE_BASIC_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter.

FileEaInformation

A FILE_EA_INFORMATION structure. This structure specifies the size of the extended attributes block that is associated with the file.

FileInternalInformation

A FILE_INTERNAL_INFORMATION structure. This structure specifies a 64-bit file ID that uniquely identifies a file in NTFS. On other file systems, this file ID is not guaranteed to be unique.

FileIoPriorityHintInformation

A FILE_IO_PRIORITY_HINT_INFORMATION structure. The caller must have opened the file with the FILE_READ_DATA flag specified in the DesiredAccess parameter.

FileModeInformation

A FILE_MODE_INFORMATION structure. This structure contains a set of flags that specify the mode in which the file can be accessed. These flags are a subset of the options that can be specified in the CreateOptions parameter of the IoCreateFile routine.

FileNameInformation

A FILE_NAME_INFORMATION structure. The structure can contain the file's full path or only a portion of it. The caller can query this information as long as the file is open, without any particular requirements for DesiredAccess.

For more information about the file-name syntax, see the Remarks section later in this topic.

FileNetworkOpenInformation

A FILE_NETWORK_OPEN_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter.

FilePositionInformation

A FILE_POSITION_INFORMATION structure. The caller must have opened the file with the DesiredAccess FILE_READ_DATA or FILE_WRITE_DATA flag specified in the DesiredAccess parameter, and with the FILE_SYNCHRONOUS_IO_ALERT or FILE_SYNCHRONOUS_IO_NONALERT flag specified in the CreateOptions parameter.

FileStandardInformation

A FILE_STANDARD_INFORMATION structure. The caller can query this information as long as the file is open, without any particular requirements for DesiredAccess.

 

Return value

ZwQueryInformationFile returns STATUS_SUCCESS or an appropriate NTSTATUS error code.

Remarks

ZwQueryInformationFile 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 ZwCreateFile, ZwQueryInformationFile returns that full path.

  • If the ObjectAttributes->RootDirectory handle was opened by name in a call to ZwCreateFile, and subsequently the file was opened by ZwCreateFile relative to this root-directory handle, ZwQueryInformationFile 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 ZwCreateFile, and subsequently the file was opened by ZwCreateFile relative to this root-directory handle, ZwQueryInformationFile returns the relative path.

  • However, if the user has SeChangeNotifyPrivilege (described in the Microsoft Windows SDK documentation), ZwQueryInformationFile 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 ZwQueryInformationFile 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 ZwQueryInformationFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

Note  If the call to this function occurs in user mode, you should use the name "NtQueryInformationFile" instead of "ZwQueryInformationFile".

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL (see Remarks section)

DDI compliance rules

PowerIrpDDis, HwStorPortProhibitedDDIs

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_MODE_INFORMATION
FILE_NAME_INFORMATION
FILE_NETWORK_OPEN_INFORMATION
FILE_POSITION_INFORMATION
FILE_STANDARD_INFORMATION
ZwCreateFile
ZwSetInformationFile

 

 

Send comments about this topic to Microsoft

顯示:
© 2014 Microsoft