The FILE_COPY procedure copies files, or directories of files, to a new location.

FILE_COPY copies files based on their names. To copy data between open files, see the COPY_LUN procedure.

Examples

Make a backup copy of a file named myroutine.pro in the current working directory:

FILE_COPY, 'myroutine.pro', 'myroutine.pro.backup'

Create a subdirectory named BACKUP in the current working directory and copy all .pro files, makefile, and mydata.dat into it:

FILE_MKDIR, 'BACKUP'
FILE_COPY, ['*.pro', 'makefile', 'mydata.dat'], 'BACKUP'

Syntax

FILE_COPY, SourcePath, DestPath [, /ALLOW_SAME] [, /NOEXPAND_PATH] [, /OVERWRITE] [, /RECURSIVE] [, /REQUIRE_DIRECTORY] [, /VERBOSE]

UNIX-Only Keywords: [, /COPY_NAMED_PIPE] [, /COPY_SYMLINK] [, /FORCE]

Arguments

SourcePath

A scalar string or string array containing the names of the files or directories to be copied.

Note: If SourcePath contains a directory, the RECURSIVE keyword must be set.

DestPath

A scalar string or string array containing the names of the destinations to which the files and directories specified by SourcePath are to be copied. If more than one file is to be copied to a given destination, that destination must exist and be a directory.

Keywords

ALLOW_SAME

Attempting to copy a file on top of itself by specifying the same file for SourcePath and DestPath is usually considered to be an error. If the ALLOW_SAME keyword is set, no copying is done and the operation is considered successful.

COPY_NAMED_PIPE

This keyword is only available on UNIX platforms.

When FILE_COPY encounters a UNIX named pipe (also called a fifo) in SourcePath, it usually opens it as a regular file and attempts to copy data from it to the destination file. If COPY_NAMED_PIPE is set, FILE_COPY will instead replicate the pipe, creating a new named pipe at the destination using the system mkfifo() function.

COPY_SYMLINK

This keyword is only available on UNIX platforms.

When FILE_COPY encounters a UNIX symbolic link in SourcePath, it attempts to copy the file or directory pointed to by the link. If COPY_SYMLINK is set, FILE_COPY will instead create a symbolic link at the destination with the same name as the source symbolic link, and pointing to the same path as the source.

FORCE

This keyword is only available on UNIX platforms.

Even if the OVERWRITE keyword is set, FILE_COPY does not overwrite files that have their file permissions set to prevent it. If the FORCE keyword is set, such files are quietly removed to make way for the overwrite operation to succeed.

Note: FORCE does not imply OVERWRITE; both must be specified to overwrite a protected file.

NOEXPAND_PATH

Set this keyword to cause FILE_COPY to use SourcePath and DestPath exactly as specified, without expanding any wildcard characters or environment variable names included in the paths. See FILE_SEARCH for details on path expansion.

OVERWRITE

Set this keyword to allow FILE_COPY to overwrite an existing file.

RECURSIVE

Set this keyword to cause directories specified by SourcePath to be copied to DestPath recursively, preserving the hierarchy and names of the files from the source. If SourcePath includes one or more directories, the RECURSIVE keyword must be set.

Note: On a UNIX system, when performing a recursive copy on a directory hierarchy that includes files that are links to other files, the destination files will be copies, not links. Setting the COPY_SYMLINK keyword will cause files that are symbolic links to be copied as symbolic links, but FILE_COPY does not include a similar facility for copying hard links. See the description of the FILE_LINK for more information on UNIX file links.

REQUIRE_DIRECTORY

Set this keyword to cause FILE_COPY to require that DestPath exist and be a directory.

VERBOSE

Set this keyword to cause FILE_COPY to issue an informative message for every file copy operation it carries out.

Rules Used By FILE_COPY

The following rules govern how FILE_COPY operates:

  • The arguments to FILE_COPY can be scalar or array. If both arguments are arrays, the arrays must contain the same number of elements; in this case, the files are copied pairwise, with each file from SourcePath being copied to the corresponding file in the DestPath. If SourcePath is an array and DestPath is a scalar, all files in SourcePath are copied to the single location given by DestPath, which must exist and be a directory.
  • Elements of SourcePath may use wildcard characters (as accepted by the FILE_SEARCH function) to specify multiple files. All the files matched for a given element of SourcePath are copied to the location specified by the corresponding element of DestPath. If multiple files are copied to a single element of DestPath, that element must exist and be a directory.
  • If a file specified in DestPath does not exist, the corresponding file from SourcePath is copied using the name specified by DestPath. Any parent directories to the file specified by DestPath must already exist. The permission settings of the source file will also be copied, and the destination file will belong to the user that performed the copy.
  • If DestPath names an existing regular file, FILE_COPY will not overwrite it, unless the OVERWRITE keyword is specified. If the OVERWRITE keyword is specified, FILE_COPY will attempt to quietly copy the permission settings of the source file, but will not attempt to change the owner.
  • If DestPath names an existing directory and SourcePath names a regular (non-directory) file, then FILE_COPY creates a file with the same name as the file given by SourcePath within the DestPath directory.
  • If DestPath specifies an existing directory and SourcePath also names a directory, and the RECURSIVE keyword is set, FILE_COPY checks for the existence of a subdirectory of DestPath with the same name as the source directory. If this subdirectory does not exist, it is created using the same permissions as the directory being copied. Then, all the files and directories underneath the source directory are copied to this subdirectory. FILE_COPY will refuse to overwrite existing files within the destination subdirectory unless the OVERWRITE keyword is in effect.

Version History

5.6

Introduced

See Also

COPY_LUN, FILE_LINK, FILE_MOVE, General File Access