FSCTL_QUERY_ALLOCATED_RANGES control code

Scans a file or alternate stream looking for ranges that may contain nonzero data. Only compressed or sparse files can have zeroed ranges known to the operating system. For other files, the output buffer will contain only a single entry that contains the starting point and the length requested.

To perform this operation, call the DeviceIoControl function with the following parameters.



BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to file
  FSCTL_QUERY_ALLOCATED_RANGES,    // dwIoControlCode
  (LPVOID) lpInBuffer,             // input buffer
  (DWORD) nInBufferSize,           // size of input buffer
  (LPVOID) lpOutBuffer,            // output buffer
  (DWORD) nOutBufferSize,          // size of output buffer
  (LPDWORD) lpBytesReturned,       // number of bytes returned
  (LPOVERLAPPED) lpOverlapped      // OVERLAPPED structure
);

Parameters

hDevice

A handle to the file or alternate stream to be queried for allocated ranges. To retrieve a handle, use the CreateFile function.

dwIoControlCode

The control code for the operation. Use FSCTL_QUERY_ALLOCATED_RANGES for this operation.

lpInBuffer

A pointer to a FILE_ALLOCATED_RANGE_BUFFER structure that indicates the portion of the file to search for allocated ranges. The FileOffset member indicates the offset, in bytes, to the first byte of the range to search, and the Length member indicates its size, in bytes.

nInBufferSize

The size of the input buffer, in bytes.

lpOutBuffer

A pointer to a buffer that receives an array of FILE_ALLOCATED_RANGE_BUFFER structures. Each structure in the array provides information about an allocated range within the file. The FileOffset member of each structure indicates the beginning of a range, and the Length member indicates its size, in bytes.

Ranges returned are always at least partially within the range specified in the lpInBuffer buffer.

nOutBufferSize

The size of the output buffer, in bytes.

lpBytesReturned

A pointer to a variable that receives the size of the data stored in the output buffer, in bytes.

If the output buffer is too small to receive any data, the call fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and lpBytesReturned is zero (0).

If the output buffer is too small to hold all of the data but can hold some entries, some drivers will return as much data as fits. In this case, the call fails, GetLastError returns ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data received. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL, lpBytesReturned cannot be NULL. Even when an operation returns no output data and lpOutBuffer is NULL, DeviceIoControl makes use of lpBytesReturned. After such an operation, the value of lpBytesReturned is meaningless.

If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this parameter is not NULL and the operation returns data, lpBytesReturned is meaningless until the overlapped operation has completed. To retrieve the number of bytes returned, call GetOverlappedResult. If hDevice is associated with an I/O completion port, you can retrieve the number of bytes returned by calling GetQueuedCompletionStatus.

lpOverlapped

A pointer to an OVERLAPPED structure.

If hDevice was opened without specifying FILE_FLAG_OVERLAPPED, lpOverlapped is ignored.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped must point to a valid OVERLAPPED structure that contains a handle to an event object. Otherwise, the function fails in unpredictable ways.

For overlapped operations, DeviceIoControl returns immediately, and the event object is signaled when the operation has been completed. Otherwise, the function does not return until the operation has been completed or an error occurs.

Return value

If the operation completes successfully, DeviceIoControl returns a nonzero value, and the output buffer pointed to by lpOutBuffer contains an array of valid FILE_ALLOCATED_RANGE_BUFFER structures.

If the operation fails or is pending, DeviceIoControl returns zero (0). The contents of the output buffer pointed to by lpOutBuffer are meaningless. For extended error information, call GetLastError.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

The NTFS file system rounds the input file offset down to a convenient boundary and the length up to a convenient boundary and then begins to walk through the file.

The operating system does not track every piece of zero (0) or nonzero data. Because zero (0) is often a perfectly legal datum, it would be misleading. Instead, the system tracks ranges where disk space is allocated. Where no disk space is allocated, all data are assumed to be zero (0). Allocated storage can contain zero (0) or nonzero data. So all this operation does is return information about parts of the file where nonzero data may be located. It is up to the application to scan these parts of the file in accordance with the application's data conventions.

Each entry in the output array contains an offset and a length that indicates a range in the file that may contain nonzero data. The actual nonzero data, if any, is somewhere within this range, and the calling program must scan further within the range to locate it and determine if it really is valid data. Multiple instances of valid data may exist within the range.

Allocated ranges are subject to the rule that a memory mapped remote (network) file and an open handle to the file are not necessarily coherent. If you memory mapped a sparse network file and wrote nonzero data to previously unallocated regions of the file, disk space would be allocated for the new data. However, a call to FSCTL_QUERY_ALLOCATED_RANGES thereafter would not necessarily return a correct list of allocated regions. To ensure coherency between the view memory and the file handle, flush the data to the file with the FlushViewOfFile function.

In Windows 8 and Windows Server 2012, this code is supported by the following technologies.

TechnologySupported

Server Message Block (SMB) 3.0 protocol

Yes

SMB 3.0 Transparent Failover (TFO)

Yes

SMB 3.0 with Scale-out File Shares (SO)

Yes

Cluster Shared Volume File System (CsvFS)

Yes

Resilient File System (ReFS)

No

 

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

WinIoCtl.h (include Windows.h)

See also

DeviceIoControl
FILE_ALLOCATED_RANGE_BUFFER
File Management Control Codes
FSCTL_SET_SPARSE
FSCTL_SET_ZERO_DATA
Sparse Files

 

 

Show: