FSCTL_MOVE_FILE IOCTL

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.

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

Major code

IRP_MJ_DEVICE_CONTROL

Input buffer

Input buffer length

Output buffer

Output buffer length

Input / Output buffer

Input / Output buffer length

Status block

Irp->IoStatus.Status is set to STATUS_SUCCESS if the request is successful.

Otherwise, Status to the appropriate error condition as a NTSTATUS code.

For more information, see NTSTATUS Values.

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

   
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

CreateFile

Defragmenting Files

DeviceIoControl

Disk Management Control Codes

FSCTL_GET_VOLUME_BITMAP

GetLastError

GetOverlappedResult

GetQueuedCompletionStatus

MOVE_FILE_DATA

OVERLAPPED