copyfile

Copy file or folder

Syntax

copyfile source

copyfile source destination

copyfile source destination f

status = copyfile(___)

[status,msg] = copyfile(___)

[status,msg,msgID] = copyfile(___)

Description

copyfile source copies the file or folder source to the current folder. After a successful copyfile operation, the timestamp for the new file is the same as the timestamp for source.

copyfile source destination copies source to the file or folder destination.

• If source is a file, then destination can be a file or an existing folder.

• If source is a folder, then destination must be a folder.

• If source is a folder or specifies multiple files and destination does not exist, then copyfile attempts to create destination.

copyfile source destination f copies source to destination, even when destination is not writable. The state of the read/write attribute for destination does not change.

status = copyfile(___) copies the specified file or folder and returns a status of 1 if the operation is successful. Otherwise, copyfile returns 0. You can use this syntax with any of the input argument combinations in the previous syntaxes.

[status,msg] = copyfile(___) also returns the message text for any warning or error that occurs.

[status,msg,msgID] = copyfile(___) additionally returns the message ID for any warning or error that occurs.

Examples

Copy File to Another Folder

Copy myfile1.m from the current folder to the subfolder myFolder.

mkdir myFolder
copyfile myfile1.m myFolder

Create Copy of File in Current Folder

Create a copy of myfile1.m in the current folder, assigning it the name myfile2.m.

copyfile myfile1.m myfile2.m

Copy Files and Folder to New Folder

Copy files and subfolders with names beginning with my from the current folder to the folder newFolder, where newFolder does not already exist.

copyfile my* newFolder

Copy File to Read-Only Folder

Copy the file myfile1.m from the current folder to the read-only folder restricted.

Create the read-only folder restricted.

mkdir restricted
fileattrib restricted -w

Copy and rename the file myfile1.m. A status of 0 shows the copy was unsuccessful.

status = copyfile('myfile1.m', 'restricted');
status

status = logical
   0

Copy the file myfile1.m using the 'f' option to override the read-only status of the destination folder. A status of 1 and an empty message and messageId confirm the copy was successful.

[status,message,messageId] = copyfile('myfile1.m', 'restricted', 'f');
status

status = logical
   1

message

message =

  0x0 empty char array

messageId

messageId =

  0x0 empty char array

Input Arguments

source — File or folder to copy

character vector | string scalar

File or folder to copy, specified as a character vector or string scalar. To copy multiple files or folders, use wildcards (*).

source can be an absolute or relative path when copying local files or folders. However, to copy files and folders at a remote location, source must contain a full path specified as a uniform resource locator (URL). For more information, see Work with Remote Data.

Note

If source is a string, enclose all the inputs in parentheses. For example, copyfile("myfile.m","newfolder").

destination — File or folder destination

character vector | string scalar

File or folder destination, specified as a character vector or string scalar. destination cannot include wildcards (*).

If destination is a local location, it can be specified as an absolute or relative path. If destination is remote, it must contain a full path specified as a URL. For more information, see Work with Remote Data.

Note

If destination is a string, enclose all the inputs in parentheses. For example, copyfile("myfile.m","newfolder").

Output Arguments

status — Copy status

0 | 1

Copy status, indicating if the attempt to move the file or folder is successful, returned as 0 or 1. If the attempt is successful, the value of status is 1. Otherwise, the value is 0.

Data Types: logical

msg — Error message

character vector

Error message, returned as a character vector. If an error or warning occurs, msg contains the message text of the error or warning. Otherwise, msg is empty, ''.

msgID — Error message identifier

character vector

Error message identifier, returned as a character vector. If an error or warning occurs, msgID contains the message identifier of the error or warning. Otherwise, msgID is empty, ''.

Compatibility Considerations

Wildcard expression *.* on UNIX platforms matches only files that have an extension

Behavior changed in R2020a

Starting in R2020a, on UNIX^® platforms, the wildcard expression *.* no longer matches folders or files without an extension. In previous releases, the expression matches folders or files regardless of extension, including files without an extension. This change of behavior does not apply to Microsoft^® Windows^® platforms.

Symbolic links are treated consistently on platforms and file systems

Behavior changed in R2020a

Symbolic links (or symlinks) are file system objects that point to target files or folders. Starting in R2020a, the behavior of the copyfile function changes when operating on symlink files or folders.

• Copy outcome is platform independent: copyfile now treats symlinks on different operating systems in the same way. For example, consider a folder structure with a file myFile.m and a symlink pointing to myFile.m, specified as symlinkToMyFile.

  myFile.m
  symlinkToMyFile
  

  Starting in R2020a, copyfile('symlinkToMyFile','newFile') copies the target of the symlink (that is, myFile.m) to the destination. In previous releases, on Linux^®, copyfile copies the symlink instead.

  Platform	newFile (Starting in R2020a)	newFile (R2019b and Earlier)
  Linux	myFile.m	symlinkToMyFile
  Mac	myFile.m	myFile.m
  Windows	myFile.m	myFile.m

• copyfile copies only the contents of the source folder: When copying a nonempty folder to a symlink folder, copyfile now copies the contents of the source folder (that is, the files and folders within the source folder) rather than the entire source folder. Similarly, when copying a symlink folder to a destination folder, only the contents of the symlink folder are copied.

  For example, consider a folder structure on Linux consisting of a nonempty folder myFolder and a symlink to that folder named symlinkToMyFolder. This table shows the folder structure after the execution of copyfile('myFolder','simlinkToMyFolder') in different MATLAB^® releases.

  Folder Structure Before Copy	Folder Structure After Copy (Starting in R2020a)	Folder Structure After Copy (R2019b and Earlier)
  myFolder myFile.m symlinkToMyFolder	myFolder myFile.m symlinkToMyFolder myFile.m	myFolder myFile.m symlinkToMyFolder myFolder myFile.m