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

Returns

Returned values from copyfile depend on how many outputs the caller requests.

Errors

How copyfile works

• status = copyfile(source, destination) copies a file or folder and returns 1 on success and 0 on failure.
• [status, message, messageID] = copyfile(...) adds MATLAB-style diagnostics. Successful copies return empty 1x0 character arrays.
• copyfile(source, destination, 'f') forces overwrites, matching MATLAB's 'f' flag. Without the flag, existing destination files or folders prevent the copy.
• Wildcards in source (for example, *.m) copy every match. When the pattern expands to multiple items, destination must 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 =
     1

Copy a file into an existing destination folder

mkdir("archive");
fid = fopen("summary.txt", "w"); fclose(fid);
status = copyfile("summary.txt", "archive")

Expected output:

status =
     1

Force 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
messageID

Expected 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");
status

Expected output:

status =
     1

Copy 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 =
     1

Handle missing sources gracefully

[status, message, messageID] = copyfile("missing.txt", "dest.txt");
status
message
messageID

Expected output:

status =
     0
message =
Source "missing.txt" does not exist.
messageID =
RunMat:COPYFILE:FileDoesNotExist

Using copyfile with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how copyfile changes the result.

FAQ

Related Io functions

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.

Getting started · Benchmarks · Pricing