copyfile — Copy files or folders in MATLAB and RunMat.
copyfile duplicates files and folders and returns status plus optional diagnostic outputs. Wildcards, directory-tree copies, and forced overwrite ('f') behavior follow MATLAB semantics.
Syntax
status = copyfile(source, destination)
status = copyfile(source, destination, flag)
[status, msg, msgID] = copyfile(source, destination)
[status, msg, msgID] = copyfile(source, destination, flag)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
source | StringScalar | Yes | — | Source file/folder path or wildcard pattern. |
destination | StringScalar | Yes | — | Destination path. |
flag | StringScalar | Yes | "f" | Overwrite flag; only "f" is accepted. |
Returns
| Name | Type | Description |
|---|---|---|
status | NumericScalar | 1 on success, 0 when copy fails. |
msg | StringScalar | Diagnostic message for failures. |
msgID | StringScalar | Stable diagnostic identifier string. |
Returned values from copyfile depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:copyfile:NotEnoughInputs | Fewer than two input arguments are provided. | copyfile: not enough input arguments |
RunMat:copyfile:TooManyInputs | More than three input arguments are provided. | copyfile: too many input arguments |
RunMat:copyfile:SourceArgType | Source argument is not a character vector or string scalar. | copyfile: source must be a character vector or string scalar |
RunMat:copyfile:DestinationArgType | Destination argument is not a character vector or string scalar. | copyfile: destination must be a character vector or string scalar |
RunMat:copyfile:FlagArgType | Flag argument is not the scalar character 'f'. | copyfile: flag must be the character 'f' supplied as a char vector or string scalar |
RunMat:copyfile:OSError | Filesystem copy operation fails. | copyfile: unable to copy |
RunMat:copyfile:FileDoesNotExist | Source path or wildcard match does not exist. | copyfile: source not found |
RunMat:copyfile:DestinationExists | Destination already exists and overwrite is not requested. | copyfile: destination already exists |
RunMat:copyfile:DestinationNotFound | Destination directory is missing for wildcard source copies. | copyfile: destination folder not found |
RunMat:copyfile:DestinationNotDirectory | Destination must be a directory for wildcard or directory copy modes. | copyfile: destination is not a directory |
RunMat:copyfile:EmptySource | Source path is empty. | Source file or folder name must not be empty. |
RunMat:copyfile:EmptyDestination | Destination path is empty. | Destination file or folder name must not be empty. |
RunMat:copyfile:InvalidPattern | Source wildcard pattern is invalid. | copyfile: invalid source pattern |
RunMat:copyfile:SourceEqualsDestination | Source and destination resolve to the same path. | copyfile: source and destination are the same |
How copyfile works
status = copyfile(source, destination)copies a file or folder and returns1on success and0on failure.[status, message, messageID] = copyfile(...)adds MATLAB-style diagnostics. Successful copies return empty1x0character arrays.copyfile(source, destination, 'f')forces overwrites, matching MATLAB's'f'flag. Without the flag, existing destination files or folders prevent the copy.- MATLAB command form is supported for literal path arguments, including
copyfile ./source.m ./archive/source.mandcopyfile ./source.m ./archive/source.m f. - Wildcards in
source(for example,*.m) copy every match. When the pattern expands to multiple items,destinationmust be an existing folder; each match is copied into that folder. - Folder copies replicate the entire directory tree, including nested files and subfolders, honoring read-only attributes where possible.
- Inputs accept character vectors or string scalars. Other types raise MATLAB-compatible errors before any filesystem work occurs.
- Paths resolve relative to the current working directory (
pwd), and a leading~expands to the user's home directory on supported platforms.
Does RunMat run copyfile on the GPU?
copyfile performs host-side filesystem I/O. When acceleration providers are active, RunMat first gathers any GPU-resident path arguments (for example, gpuArray("data")) back to CPU memory, executes the copy entirely on the host, and returns host-resident outputs. Providers do not implement dedicated hooks for this builtin, so no GPU kernels are dispatched.
GPU memory and residency
No. copyfile always runs on the CPU. If callers supply GPU-resident strings, RunMat automatically gathers them before touching the filesystem so existing code continues to work. Keeping paths on the GPU offers no performance benefit.
Examples
Copy a file into a new name in the same folder
fid = fopen("report.txt", "w"); fclose(fid);
status = copyfile("report.txt", "report_backup.txt")Expected output:
status =
1Copy a file into an existing destination folder
mkdir("archive");
fid = fopen("summary.txt", "w"); fclose(fid);
status = copyfile("summary.txt", "archive")Expected output:
status =
1Force overwrite an existing destination file
fid = fopen("draft.txt", "w"); fclose(fid);
fid = fopen("final.txt", "w"); fclose(fid);
[status, message, messageID] = copyfile("draft.txt", "final.txt", "f");
status
message
messageIDExpected output:
status =
1
message =
messageID =Copy an entire folder tree
mkdir("data/raw");
fid = fopen(fullfile("data", "raw", "sample.dat"), "w"); fclose(fid);
status = copyfile("data", "data_copy");
statusExpected output:
status =
1Copy multiple files with a wildcard pattern
fid = fopen("a.log", "w"); fclose(fid);
fid = fopen("b.log", "w"); fclose(fid);
mkdir("logs");
status = copyfile("*.log", "logs")Expected output:
status =
1Handle missing sources gracefully
[status, message, messageID] = copyfile("missing.txt", "dest.txt");
status
message
messageIDExpected output:
status =
0
message =
Source "missing.txt" does not exist.
messageID =
RunMat:COPYFILE:FileDoesNotExistUsing copyfile with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how copyfile changes the result.
Run a small copyfile example, explain the result, then change one input and compare the output.
FAQ
What status codes does copyfile return?⌄
1 on success, 0 on failure. The numeric output is a double scalar to match MATLAB.
Does copyfile throw exceptions?⌄
Only invalid inputs raise immediate errors. Filesystem failures surface through status, message, and messageID.
How do I overwrite existing files?⌄
Pass 'f' as the third argument. Without it, existing destinations prevent the copy.
Can I copy folders recursively?⌄
Yes. When source refers to a folder, copyfile copies its entire contents (including subfolders) into destination.
What happens when the source and destination are the same?⌄
The builtin reports a failure with messageID = RunMat:COPYFILE:SourceEqualsDestination, mirroring MATLAB's diagnostics.
Does copyfile preserve timestamps and permissions?⌄
It delegates to the host operating system. RunMat attempts to preserve read-only attributes where possible, but platform differences may leave some metadata unchanged.
Can copyfile create intermediate destination folders?⌄
copyfile does not invent new parent folders. Ensure the destination's parent path exists before calling the builtin.
Will GPU acceleration speed up copyfile?⌄
No. The builtin operates entirely on the host CPU. GPU-resident strings are gathered automatically so existing scripts remain compatible.
Are wildcards supported on all platforms?⌄
Yes. copyfile("*.txt", "dest") expands using MATLAB-compatible glob semantics on every supported operating system.
Related Io functions
Repl Fs
addpath · cd · delete · dir · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how copyfile is executed, line by line, in Rust.
- View the source for copyfile in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.