FSCTL_QUERY_ALLOCATED_RANGES IOCTL (ntifs.h)

Article
10/09/2023

FSCTL_QUERY_ALLOCATED_RANGES requests a scan of a file or alternate stream looking for byte ranges that can contain nonzero data, and then return of information on those ranges. Only sparse files can have zeroed ranges known to the operating system. For other files, the output buffer will contain only a single range that contains the starting point and the length requested.

Major code

FSCTL_QUERY_ALLOCATED_RANGES

Input buffer

Pointer to a FILE_ALLOCATED_RANGE_BUFFER structure that indicates the range to query for allocation.

Input buffer length

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

Output buffer

Pointer to an array of zero or more FILE_ALLOCATED_RANGE_BUFFER data elements in which the results of the query are returned. See below for more information.

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 that contains the final status of the request.
FsControlCode	[in] Set to FSCTL_QUERY_ALLOCATED_RANGES.
InputBuffer	[in] Pointer to a FILE_ALLOCATED_RANGE_BUFFER structure that indicates the range to query for allocation.
InputBufferLength	[in] Size of the buffer that InputBuffer points to, in bytes.
OutputBuffer	[out] Pointer to an array of zero or more FILE_ALLOCATED_RANGE_BUFFER data elements in which the results of the query are returned. See below for more information.
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.

FSCTL_QUERY_ALLOCATED_RANGES returns an array of zero or more FILE_ALLOCATED_RANGE_BUFFER data elements in the buffer that OutputBuffer points to. The number of FILE_ALLOCATED_RANGE_BUFFER elements returned is computed by dividing the value returned in LengthReturned by sizeof(FILE_ALLOCATED_RANGE_BUFFER). The returned ranges must intersect the range specified in InputBuffer. Zero FILE_ALLOCATED_RANGE_BUFFER data elements are returned when the file has no allocated ranges.

Return values

FSCTL_QUERY_ALLOCATED_RANGES returns STATUS_SUCCESS upon successful completion; otherwise it returns an error code. Common error codes follow.

Error code	Meaning
STATUS_INVALID_PARAMETER	A parameter is invalid. For example: the handle is not to a file; the size of InputBuffer is less than the size of a FILE_ALLOCATED_RANGE_BUFFER structure; FileOffset is less than zero; Length is less than zero; or FileOffset plus Length is larger than 0x7FFFFFFFFFFFFFFF.
STATUS_INVALID_USER_BUFFER	The input buffer or output buffer is not aligned to a 4-byte boundary.
STATUS_BUFFER_TOO_SMALL	The output buffer is too small to contain a FILE_ALLOCATED_RANGE_BUFFER structure.
STATUS_BUFFER_OVERFLOW	The output buffer is too small to contain the required number of FILE_ALLOCATED_RANGE_BUFFER structures.

Requirements

Requirement	Value
Minimum supported client	Windows 2000
Header	ntifs.h