NtCopyFileChunk function (ntifs.h)

Article
01/12/2024

The NtCopyFileChunk routine copies data from the source file into the destination file.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtCopyFileChunk(
  [in]           HANDLE           SourceHandle,
  [in]           HANDLE           DestHandle,
  [in, optional] HANDLE           Event,
  [out]          PIO_STATUS_BLOCK IoStatusBlock,
  [in]           ULONG            Length,
  [in]           PLARGE_INTEGER   SourceOffset,
  [in]           PLARGE_INTEGER   DestOffset,
  [in, optional] PULONG           SourceKey,
  [in, optional] PULONG           DestKey,
  [in]           ULONG            Flags
);

Parameters

[in] SourceHandle

The HANDLE of the source file to be read.

[in] DestHandle

The HANDLE of the destination file. The data from SourceHandle's file is copied into DestHandle's file. Completion ports can be used on this handle.

[in, optional] Event

An optional event to be signaled when the copy operation is complete.

[out] IoStatusBlock

A pointer to an IO_STATUS_BLOCK structure that receives the final completion status and other information about the copy operation.

[in] Length

The length of the data to copy, in bytes.

[in] SourceOffset

The starting byte offset within the source file to begin the read operation.

[in] DestOffset

The starting byte offset within the destination file to begin the write operation.

[in, optional] SourceKey

An optional key to be used if there are oplocks associated with the source file.

[in, optional] DestKey

An optional key to be used if there are oplocks associated with the destination file.

[in] Flags

Optional flags. Currently there are no valid flag values.

Return value

NtCopyFileChunk returns STATUS_SUCCESS if the copy is successfully completed, or an NTSTATUS code such as one of the following:

Code	Meaning
STATUS_PENDING	The copy is in progress. Callers must wait on the event or file object to get the final status.
STATUS_[ERROR]	Various errors can occur similar to NtReadFile and NtWriteFile.

Once the write completes the status of the operation can be determined by examining the Status field of IoStatusBlock.

See Remarks for details regarding the handling of synchronous/asynchronous I/O.

Remarks

NtCopyFileChunk copies data from a source file into a destination file using the provided file offsets for the requested length. If the length surpasses the end of file (EOF) on the source file, then NtCopyFileChunk will only read and copy the data to the destination up to the source’s EOF. Callers can get the actual number of bytes written from the IoStatusBlock.

NtCopyFileChunk includes two I/O operations: a read of the source file and a write to the destination file. While each I/O internally has its own completion, the caller’s event (or destination file handle if no event is provided) will be signaled when the copy operation is complete.

The source and destination files can be opened asynchronously or synchronously. While it is recommended that callers are consistent between the two handles, it is not required. Depending on the handles provided, NtCopyFileChunk will return at different points in the copy operation as specified in the following table.

Source Handle	Destination Handle	Return Conditions
Asynchronous	Asynchronous	Once the read has been successfully queued OR if there are errors prior to queuing the read.
Asynchronous	Synchronous	Once the write has finished OR if there are errors prior to write completion.
Synchronous	Synchronous	Once the write has finished OR if there are errors prior to write completion.
Synchronous	Asynchronous	Once the write has been successfully queued OR if there are errors prior to queueing the write.

If STATUS_PENDING is returned, the called must wait for the operation to complete before looking at the I/O status block for the final status. If STATUS_SUCCESS is returned or the I/O status block indicates success, the caller should look at the IoStatusBlock to determine how many bytes were copied.

If either file is opened for non-cached I/O, the caller must ensure that the requested length is sector-aligned with whichever file is opened as non-cached. If both, the length should be aligned with the larger sector size of the two.

All read and write operations from NtCopyFileChunk will have:

The IRP's requestor mode set to KernelMode
An IRP extension of type IopCopyInformationType.

Filters do not have access to the IRP extensions directly but can check the presence of this extension and get copy information from the callback data by calling FltGetCopyInformationFromCallbackData.

Fast IO is not available in this copy because the copy information is present in the IRP extension (and Fast IO doesn't create IRPs).

NtCopyFileChunk is used internally by CopyFile for most forms of copy. Current exceptions include cloud copies, SMB offload and ODX.

The following example shows how to use NtCopyFileChunk.


// Input parameters to NtCopyFileChunk. Opening
// the file handles is done using NtCreateFile
// and creating the event is done with CreateEvent.
// This is not shown in this code sample. 

HANDLE sourceHandle; 
HANDLE destHandle; 
HANDLE event; 
IO_STATUS_BLOCK ioStatusBlock; 
ULONG length; 
LARGE_INTEGER sourceOffset; 
LARGE_INTEGER destOffset; 

// Copy the data 

status = NtCopyFileChunk( sourceHandle, 
                          destHandle, 
                          event, 
                          &ioStatusBlock, 
                          length, 
                          &sourceOffset, 
                          &destOffset, 
                          NULL, 
                          NULL, 
                          0 ); 

// Wait for the copy to complete 

if (status == STATUS_PENDING) { 
    status = NtWaitForSingleObject( event, FALSE, NULL ); 

    if (NT_SUCCESS(status)) { 
        status = ioStatusBlock.Status; 
    } 
}

See Kernel-mode file copy and detecting copy file scenarios for more information.

Requirements

Requirement	Value
Minimum supported client	Windows 11, version 22H2
Header	ntifs.h
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL