FSCTL_QUERY_ALLOCATED_RANGES

[This is preliminary documentation and subject to change.]

The FSCTL_QUERY_ALLOCATED_RANGES operation scans a file 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 a file
  FSCTL_QUERY_ALLOCATED_RANGES,    // dwIoControlCode, control code of
                           // operation to perform
  (LPVOID) lpInBuffer,     // pointer to an input buffer
  (DWORD) nInBufferSize,   // size, in bytes, of lpInBuffer
  (LPVOID) lpOutBuffer,    // pointer to an output buffer
  (DWORD) nOutBufferSize,  // size, in bytes, of lpOutBuffer
  (LPDWORD) lpBytesReturned,   // pointer to variable to receive
                           // output byte count
  (LPOVERLAPPED) lpOverlapped  // pointer to an OVERLAPPED structure
                           // for asynchronous operation
);
 

Parameters

hDevice

Handle to the file on which the operation is to be performed. Call the CreateFile function to obtain a handle. This operation cannot be called with a directory or volume handle.

dwIoControlCode

Control code for the operation. This value identifies the specific operation to be performed and the type of device on which the operation is to be performed. Use FSCTL_QUERY_ALLOCATED_RANGES for this operation.

lpInBuffer

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

Size, in bytes, of the lpInBuffer buffer.

lpOutBuffer

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

Size, in bytes, of the lpOutBuffer buffer.

lpBytesReturned

Pointer to a DWORD variable that receives the size, in bytes, of output data returned. If the lpOutBuffer buffer is too small, lpBytesReturned receives the required buffer size.

If lpOverlapped is NULL, lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this is an overlapped operation, you can get the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped

Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, this parameter must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, this parameter is ignored and the DeviceIoControl function does not return until the operation has been completed, or an error occurs.

Return Values

If the operation succeeds, 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, DeviceIoControl returns zero. The contents of the output buffer pointed to by lpOutBuffer are meaningless. For extended error information, call GetLastError.

Remarks

See the Remarks section of the DeviceIoControl topic for the implications of overlapped I/O on this operation.

NTFS 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 or nonzero data. Because zero 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. Allocated storage can contain zero 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.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Operations, DeviceIoControl, FILE_ALLOCATED_RANGE_BUFFER, FSCTL_SET_SPARSE, FSCTL_SET_ZERO_DATA