FSCTL_GET_VOLUME_BITMAP

Using the FSCTL_GET_VOLUME_BITMAP control code gets a bitmap of occupied and available clusters on a volume.

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

BOOL DeviceIoControl(
  (HANDLE) hDevice,           // handle to volume
  FSCTL_GET_VOLUME_BITMAP,    // dwIoControlCode operation
  (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

[in] Handle to the volume from which the bitmap is to be retrieved. To obtain a device handle, call the CreateFile function. Only administrators can open volume handles.

Encrypted files must be opened with FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA, or FILE_EXECUTE access. Other files need only be opened with FILE_READ_ATTRIBUTES access. For more information, see File and Directory Security.

dwIoControlCode

[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_GET_VOLUME_BITMAP for this operation.

lpInBuffer

[in] Pointer to the input buffer, a STARTING_LCN_INPUT_BUFFER structure. The starting LCN in the input buffer may be rounded down by the operation.

nInBufferSize

[in] Size, in bytes, of the input buffer.

lpOutBuffer

[out] Pointer to the output buffer, a VOLUME_BITMAP_BUFFER variably sized structure.

nOutBufferSize

[in] Size, in bytes, of the output buffer.

lpBytesReturned

[out] Pointer to a DWORD variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve 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

[in] Pointer to an OVERLAPPED structure.

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

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

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

A return value from GetLastError of ERROR_MORE_DATA indicates to the caller that the buffer was not large enough to accommodate a complete bitmap from the requested starting LCN to the last cluster on the volume. In this event, you can make subsequent FSCTL_GET_VOLUME_BITMAP calls to obtain the remaining bitmap.

A return value from GetLastError of ERROR_INVALID_PARAMETER indicates either that there is no input buffer, that the starting LCN requested in the input buffer was less than zero, or that the starting LCN was greater than or equal to the total clusters on the volume.

A return value from GetLastError of ERROR_NOT_READY indicates that the volume is an NTFS volume, and it is not mounted.

Remarks

The FSCTL_GET_VOLUME_BITMAP operation retrieves a data structure that describes the allocation state of each cluster in the file system from the requested starting LCN to the last cluster on the volume. The bitmap uses one bit to represent each cluster:

• The value 1 indicates that the cluster is allocated (in use).
• The value 0 indicates that the cluster is not allocated (free).

Note that the bitmap represents a point in time, and can be incorrect as soon as it has been read if the volume has write activity. Thus, it is possible to attempt to move a cluster onto an allocated cluster in spite of a recent bitmap indicating that the cluster is unallocated. Programs using the DeviceIoControl FSCTL_MOVE_FILE operation must be prepared for this possibility.

The handle used here must be a Volume handle and have been opened with any access. Note that only Administrators can open Volume handles.

The starting LCN in the input buffer may be rounded down before the bitmap is calculated. The rounding limit is file system dependent.

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

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, Defragmentation, DeviceIoControl, CreateFile, GetLastError, GetOverlappedResult, GetQueuedCompletionStatus, STARTING_LCN_INPUT_BUFFER, VOLUME_BITMAP_BUFFER, FSCTL_MOVE_FILE, OVERLAPPED