copyfile - Copy file or folder - MATLAB (original) (raw)

Syntax

Description

copyfile [source](#f3-467505-source) copies the file or foldersource to the current folder. After a successfulcopyfile operation, the timestamp for the new file is the same as the timestamp for source.

copyfile [source](#f3-467505-source) [destination](#f3-467505-destination) copies source to the file or folderdestination.

• If source is a file, thendestination can be a file or folder.
• If source is a folder, thendestination must be a folder.
• If source is a folder or specifies multiple files and destination does not exist, thencopyfile attempts to createdestination.

example

copyfile [source](#f3-467505-source) [destination](#f3-467505-destination) f copies source to destination, even when destination is not writable. The state of the read/write attribute for destination does not change.

example

copyfile([source](#f3-467505-source),[destination](#f3-467505-destination),CopyLinkBehavior=[slbehavior](#mw%5F7698eb25-2e21-4a32-85bf-22ec6fd742f2)) specifies whether to copy a symbolic link or its target. (since R2024b)

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

example

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

example

[[status](#f3-467505-status),[msg](#f3-467505-msg),[msgID](#f3-467505-msgID)] = copyfile(___) also returns the message ID for any warning or error that occurs.

example

Examples

collapse all

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

mkdir myFolder copyfile myfile1.m myFolder

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

copyfile myfile1.m myfile2.m

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

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

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

message =

0×0 empty char array

messageId =

0×0 empty char array

Input Arguments

collapse all

File or folder to copy, specified as a string scalar or character vector. To copy multiple files or folders, use wildcards (*). When copying multiple files or folders, copyfile copies only the files and folders that can be copied.

source can be an absolute or relative path when copying local files or folders. However, for files and folders at a remote location, you must specify the full path as a uniform resource locator (URL). Internet URLs must include the protocol type "http://" or"https://". 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").

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

If destination is a local location, you can specify an absolute or relative path. If source is a folder and thedestination folder does not exist,copyfile creates the folder. Ifsource is a file and thedestination folder does not exist,copyfile instead creates a file using the folder name, with no extension. To write a file to a destination folder, the folder must exist in advance.

If destination is a remote location, you must specify the full path of 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").

Since R2024b

Symbolic link behavior, specified as one of these values:

• "osdefault" – Use the default behavior of the file system.
• "preserve" – Copy the symbolic link and preserve it as a symbolic link at the destination. The target of the symbolic link remains the same.
• "resolve" – Copy the target of the symbolic link.

Output Arguments

collapse all

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

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,''.

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,''.

Limitations

• MATLAB® does not support internet URLs that require authentication.
• MATLAB Online™ supports internet URLs associated with Microsoft® OneDrive™ files and folders, while the installed version of MATLAB supports only local OneDrive files.

Tips

• This function supports Microsoft Windows® shortcut files (.lnk).

Extended Capabilities

expand all

Usage notes and limitations:

• The copyfile function does not support wildcard operations or URLs as input.
• Code generated from MATLAB might behave differently from its execution within MATLAB.
  In such instances, file handling in the generated code is similar to the CopyFileExA function on Windows platforms or the read andwrite functions on UNIX® systems in the C language.

Version History

Introduced before R2006a

expand all

You can read data from primary online sources by performing file read operations over an internet URL.

You can copy files and folders using symbolic links. When you specify a symbolic link as the source, you can control whether to copy the symbolic link itself or copy its target.

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 (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 tomyFile.m, specified assymlinkToMyFile.
  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 foldermyFolder and a symlink to that folder namedsymlinkToMyFolder. This table shows the folder structure after the execution ofcopyfile('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