fn copy_file_range(fd_in: fd_t, off_in: u64, fd_out: fd_t, off_out: u64, len: usize, flags: u32) CopyFileRangeError!usize

Transfer data between file descriptors at specified offsets. Returns the number of bytes written, which can less than requested.

The copy_file_range call copies len bytes from one file descriptor to another. When possible, this is done within the operating system kernel, which can provide better performance characteristics than transferring data from kernel to user space and back, such as with pread and pwrite calls.

fd_in must be a file descriptor opened for reading, and fd_out must be a file descriptor opened for writing. They may be any kind of file descriptor; however, if fd_in is not a regular file system file, it may cause this function to fall back to calling pread and pwrite, in which case atomicity guarantees no longer apply.

If fd_in and fd_out are the same, source and target ranges must not overlap. The file descriptor seek positions are ignored and not updated. When off_in is past the end of the input file, it successfully reads 0 bytes.

flags has different meanings per operating system; refer to the respective man pages.

These systems support in-kernel data copying:

  • Linux 4.5 (cross-filesystem 5.3)
  • FreeBSD 13.0

Other systems fall back to calling pread / pwrite.

Maximum offsets on Linux and FreeBSD are math.maxInt(i64).

Parameters

fd_in: fd_t,
off_in: u64,
fd_out: fd_t,
off_out: u64,
len: usize,
flags: u32,