32.56. $copyFile

$copyFile copies a portion of the file src to the file dst. It is an error if src is not open for input or dst is not open for output. No operation is performed if src equals dst.

The amount of data to be copied is measured in character units. It is computed as:

IF NOT copyLen THEN
    end-of-file position of src - current position of src
ELSE
    copyLen MIN
        (end-of-file position of src - current position of src)

$copyFile copies the amount of data to be copied, starting at the current positions of src and dst. It is more efficient than calling $storageUnitRead and $storageUnitWrite or $characterRead and $characterWrite to store the data to be copied in a temporary area.

If the files are text files and keepNul was not set in the open bits for src, null characters (and on some systems, carriage return) are discarded during the copy. In this case, the actual number of characters copied to dst is copyLen minus the number of null characters discarded. $copyFile of a text file is more efficient if keepNul was set when src was opened.

$copyFile leaves the file positions of its arguments at the end of the copied region.

When a data file is being copied, it is an error if the data formats of the input and output files differ. For example, a PDF data file cannot be copied to a native data file if the two file formats differ. If a text file is being copied and the text formats (e.g., end-of-line conventions) of the input and output files differ, the file is copied a character at a time so that any necessary translation can be done.