RunMat
GitHub

View all functions

CategoryIo: Repl Fs

copyfile — Copy files or folders with MATLAB-compatible status, diagnostic message, and message ID outputs.

copyfile duplicates files and folders. It mirrors MATLAB's behavior by returning a numeric status plus optional diagnostic text instead of throwing exceptions for filesystem failures. The builtin understands wildcards, directory trees, and the optional 'f' flag that forces overwrites of existing targets.

How does the copyfile function behave in MATLAB / RunMat?

  • 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.

GPU behavior

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 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 of using copyfile in MATLAB / RunMat

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 =
MATLAB:COPYFILE:FileDoesNotExist

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 = MATLAB: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.

See also

movefile, mkdir, rmdir, dir, pwd

Source & Feedback