Platform SDK: Hardware

FSCTL_MOVE_FILE

Using 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.

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

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

Parameters

hDevice

[in] Handle to the volume that contains the file or directory whose clusters are to be moved. 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_MOVE_FILE for this operation.

lpInBuffer

[in] Pointer to the input buffer, a MOVE_FILE_DATA structure.

nInBufferSize

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

lpOutBuffer

[out] Pointer to the output buffer. Not used; must be NULL.

nOutBufferSize

[in] Size, in bytes, of the output buffer. Not used; must be zero.

lpBytesReturned

[out] Pointer to a DWORD variable that receives the actual count of bytes returned by the function in the output buffer. The lpBytesReturned value is meaningless because there is no output buffer. With an asynchronous call, the programmer must provide a non-NULL pointer to a valid DWORD.

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

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL.

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 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. The possible return values for GetLastError include the following values.

Last Error	Interpretation
ERROR_INVALID_PARAMETER	One or more of the following: One or more of the logical clusters to which the file's virtual clusters are to be moved is an allocated cluster. The handle used for the IOCTL is not a DASD (volume) handle. The FileHandle member passed in the MOVE_FILE_DATA structure is not on the same volume as the volume handle specified in hDevice. The FileHandle member of the MOVE_FILE_DATA structure was for a paging file, change journal, or a file type other than a file, directory, or view index. The StartingVcn, StartingLcn, or ClusterCount member contains an invalid value. The FileHandle member is to an encrypted file, but the handle does not have FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA, or FILE_EXECUTE. This means that there is no security context for moving the data between cache and disk, so the FSCTL_MOVE_FILE operation cannot complete.
ERROR_INVALID_FUNCTION	This is an NTFS volume with a cluster size greater than 4KB.
ERROR_INSUFFICIENT_BUFFER	This is an NTFS volume and the input buffer was smaller than sizeof(MOVE_FILE_DATA).
ERROR_NOT_READY	The volume is NTFS and is unmounted.
ERROR_GEN_FAILURE	Typically, this means that on NTFS, another compress or FSCTL_MOVE_FILE operation is happening at the same time on the file specified by the FileHandle member.

Note that when a move operation returns with a failure, some of the clusters may have been moved. To determine if this is the case, you have to acquire a new bitmap or retrieve new pointers.

Remarks

The FSCTL_MOVE_FILE operation 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.

Note that the bitmap returned by the DeviceIoControl FSCTL_GET_VOLUME_BITMAP operation 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.

Requirements

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

FSCTL_MOVE_FILE

Parameters

Return Values

Remarks

Requirements

See Also