FSCTL_QUERY_FILE_REGIONS IOCTL (ntifs.h)

Article
10/09/2023

FSCTL_QUERY_FILE_REGIONS queries a list of file regions, based on a specified usage parameter, for the file associated with the handle on which this FSCTL was invoked. This message contains an optional FILE_REGION_INPUT data element. If no FILE_REGION_INPUT parameter is specified, information for the entire size of the file is returned.

Major code

FSCTL_QUERY_FILE_REGIONS

Input buffer

Pointer to a FILE_REGION_INPUT structure that indicates the file region(s) to query.

Input buffer length

Size of the FILE_REGION_INPUT structure that InputBuffer points to, in bytes.

Output buffer

Pointer to a FILE_REGION_OUTPUT structure in which the results of the query are returned.

Output buffer length

Size of the buffer that OutputBuffer points to, in bytes.

Input / Output buffer

n/a

Input / Output buffer length

n/a

Status block

Reserved for system use.

Remarks

To perform this operation, call FltFsControlFile or ZwFsControlFile with the following parameters.

Parameter	Description
Instance	[in] For FltFsControlFile only. An opaque instance pointer for the caller. This parameter is required and cannot be NULL.
FileObject	[in] For FltFsControlFile only. A file object pointer for the file or directory that is the target of this request. This parameter is required and cannot be NULL.
FileHandle	[in] For ZwFsControlFile only. File handle of the file or directory that is the target of this request. This parameter is required and cannot be NULL.
IoStatusBlock	[out] For ZwFsControlFile only. Pointer to an IO_STATUS_BLOCK structure in which the final status of the request is returned.
FsControlCode	[in] Set to FSCTL_QUERY_FILE_REGIONS.
InputBuffer	[in/optional] Pointer to a FILE_REGION_INPUT structure that indicates the file region(s) to query.
InputBufferLength	[in] Size of the buffer that InputBuffer points to, in bytes.
OutputBuffer	[out] Pointer to a FILE_REGION_OUTPUT structure in which the results of the query are returned.
OutputBufferLength	[out] Size of the buffer that OutputBuffer points to, in bytes.
LengthReturned	[out] Pointer to a caller-allocated variable that receives the size in bytes of the information returned in the buffer at OutputBuffer.

Return values

FSCTL_QUERY_FILE_REGIONS returns STATUS_SUCCESS upon successful completion; otherwise it returns an error code. On successful completion, the caller should first verify that IoStatus.Information is greater than or equal to LengthReturned before accessing the information returned in OutputBuffer.

Requirements

Requirement	Value
Minimum supported client	Windows 8
Header	ntifs.h