Copies file a to destination b and returns file path of the destination file. If b is a directory file a will be copied to that directory without changing the filename. If b is a new filename, the file will be copied with the new name. If the destination directory does not already exist, an attempt is made to create it. If this is not possible, the processing is cancelled with an error.

Parameter b is then interpreted as a directory if it is an existing directory, or if the path name ends with a path separator. The right slash / is expected as a path separator (also under Windows).

The function ends with an error if parameter a does not identify an existing file, and if copying to target path b is not possible, e. g. because the target directory could not be created or if the user did not have sufficient rights for that.

When the file is successfully copied, the full path of the copied file (target file) is returned as the result of the function call.