FSCTL_MOVE_FILE IOCTL (winioctl.h)

  • Article

Relocates one or more virtual clusters of a file from one logical cluster to another within the same volume. This operation is used during defragmentation.

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

BOOL DeviceIoControl(
  (HANDLE) hDevice,             // handle to volume
  FSCTL_MOVE_FILE,              // dwIoControlCode
  (LPVOID) lpInBuffer,          // MOVE_FILE_DATA structure
  (DWORD) nInBufferSize,        // size of input buffer
  NULL,                         // lpOutBuffer
  0,                            // nOutBufferSize
  (LPDWORD) lpBytesReturned,    // number of bytes returned
  (LPOVERLAPPED) lpOverlapped   // OVERLAPPED structure
);

Remarks

The FSCTL_MOVE_FILE control code relocates one or more virtual clusters of a file from one logical cluster to another within the same volume. If the file to be moved is a sparse or compressed file, the granularity of the move is 16 clusters; otherwise, the granularity is one cluster.

To mark an open file so that it is not defragmented, call the DeviceIoControl function with the FSCTL_MARK_HANDLE control code with MARK_HANDLE_PROTECT_CLUSTERS in the HandleInfo member of the MARK_HANDLE_INFO structure passed in the lpInBuffer parameter.

Note that the bitmap returned by the DeviceIoControl function with the FSCTL_GET_VOLUME_BITMAP control code 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 FSCTL_MOVE_FILE must be prepared for this possibility.

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

For a list of files, streams, and stream types supported by the FSCTL_MOVE_FILE control code, see the Files, streams, and stream types supported for defragmentation section of the Defragmenting Files topic.

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

Technology Supported
Server Message Block (SMB) 3.0 protocol No
SMB 3.0 Transparent Failover (TFO) No
SMB 3.0 with Scale-out File Shares (SO) No
Cluster Shared Volume File System (CsvFS) Yes

Requirements

Requirement Value
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