copyfile — Copy files, directory trees, or wildcard matches.
copyfile duplicates filesystem content and returns status with optional diagnostics.
Syntax
[status, msg, msgID] = copyfile(source, destination)
[status, msg, msgID] = copyfile(source, destination, flag)Inputs
source- Type
StringScalar- Required
- Yes
- Description
- Source file, directory, or wildcard pattern.
destination- Type
StringScalar- Required
- Yes
- Description
- Destination file or directory path.
flag- Type
StringScalar- Required
- Yes
- Default
'f'- Description
- Case-insensitive 'f' flag that permits replacement of an existing target.
Returns
status- Type
NumericScalar- Description
- Double scalar 1 after success or 0 after an operational failure.
msg- Type
StringScalar- Description
- Character-row diagnostic, empty after success.
msgID- Type
StringScalar- Description
- Character-row diagnostic identifier, empty after success.
Returned values from copyfile depend on how many outputs the caller requests.
Errors
RunMat:copyfile:NotEnoughInputs- When
- Fewer than two inputs are provided.
- Message
copyfile: not enough input arguments
RunMat:copyfile:TooManyInputs- When
- More than three inputs are provided.
- Message
copyfile: too many input arguments
RunMat:copyfile:SourceArgType- When
- Source is not a character row or string scalar.
- Message
copyfile: source must be a character vector or string scalar
Copy files and directories
copyfile(source, destination) copies one file or directory. A directory source includes its descendants. A source containing wildcards copies every match into an existing destination directory.
Pass 'f' as the third argument to replace an existing destination. Without that flag, an existing target is preserved and the operation reports failure.
Results and execution
status is a double scalar: 1 after success and 0 after an operational failure. msg and msgID are empty character rows after success and describe a failure otherwise. Invalid argument types and malformed flags raise an error before filesystem access.
Paths accept character rows and scalar strings. Relative paths use the current folder and a leading ~ expands through the active environment. The operation runs through the host or browser filesystem service; provider-resident inputs gather before parsing, and no accelerator kernel is used.
File contents and directory trees are copied. Read-only state is preserved where the filesystem exposes it; other timestamps, permissions, links, and platform metadata remain subject to the active filesystem provider.
Examples
Copy a file to a new name
root = tempname();
mkdir(root);
source = fullfile(root, 'report.txt');
target = fullfile(root, 'report-copy.txt');
fid = fopen(source, 'w'); fclose(fid);
status = copyfile(source, target);
copied = exist(target, 'file');
rmdir(root, 's');Expected output:
status is double 1 and the destination file existsCopy a file into a directory
root = tempname();
mkdir(root);
mkdir(root, 'archive');
source = fullfile(root, 'summary.txt');
fid = fopen(source, 'w'); fclose(fid);
status = copyfile(source, fullfile(root, 'archive'));
copied = exist(fullfile(root, 'archive', 'summary.txt'), 'file');
rmdir(root, 's');Expected output:
the source name is retained inside the destination directoryReplace an existing file
root = tempname();
mkdir(root);
source = fullfile(root, 'draft.txt');
target = fullfile(root, 'final.txt');
fid = fopen(source, 'w'); fclose(fid);
fid = fopen(target, 'w'); fclose(fid);
[status, msg, msgID] = copyfile(source, target, 'f');
rmdir(root, 's');Expected output:
status is 1 and both diagnostic character rows are emptyCopy a directory tree
root = tempname();
mkdir(root, fullfile('data', 'raw'));
source = fullfile(root, 'data');
fid = fopen(fullfile(source, 'raw', 'sample.dat'), 'w'); fclose(fid);
target = fullfile(root, 'data-copy');
status = copyfile(source, target);
copied = exist(fullfile(target, 'raw', 'sample.dat'), 'file');
rmdir(root, 's');Expected output:
the nested file is copied with the directory treeCopy every wildcard match
root = tempname();
mkdir(root);
mkdir(root, 'logs');
fid = fopen(fullfile(root, 'a.log'), 'w'); fclose(fid);
fid = fopen(fullfile(root, 'b.log'), 'w'); fclose(fid);
status = copyfile(fullfile(root, '*.log'), fullfile(root, 'logs'));
first = exist(fullfile(root, 'logs', 'a.log'), 'file');
second = exist(fullfile(root, 'logs', 'b.log'), 'file');
rmdir(root, 's');Expected output:
both matching files are copiedInspect a missing-source result
root = tempname();
mkdir(root);
[status, msg, msgID] = copyfile(fullfile(root, 'missing.txt'), fullfile(root, 'dest.txt'));
rmdir(root);Expected output:
status is 0 and the diagnostic rows identify the failureUsing 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
How do I replace an existing target?⌄
Pass 'f' as the third argument. Without it, copyfile leaves the existing target unchanged and returns status 0.
Can copyfile create destination parents?⌄
No. Create missing parent directories before the call. A directory named by destination may be created when its parent already exists.
What happens when source and destination identify the same path?⌄
The operation returns status 0, leaves the path unchanged, and supplies a SourceEqualsDestination diagnostic identifier.
Can copyfile run on a GPU?⌄
No. Filesystem access is a host-service operation. Resident arguments gather before validation and execution.
Related Io functions
Repl Fs
addpath · cd · delete · dir · exist · fileattrib · fileparts · filesep · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · memmapfile.subsasgn · memmapfile.subsref · 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 · getvaropts · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · setvaropts · setvartype · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Data
commit · data.copy · data.create · data.delete · data.exists · data.export · data.import · data.inspect · data.list · data.move · data.open · DataArray.chunk_shape · DataArray.codec · DataArray.dtype · DataArray.fill · DataArray.name · DataArray.rank · DataArray.read · DataArray.resize · DataArray.shape · DataArray.write · Dataset.array · Dataset.arrays · Dataset.attrs · Dataset.begin · Dataset.get_attr · Dataset.has_array · Dataset.id · Dataset.path · Dataset.refresh · Dataset.set_attr · Dataset.set_attrs · Dataset.snapshot · Dataset.version · DataTransaction.abort · DataTransaction.commit · DataTransaction.create_array · DataTransaction.delete_array · DataTransaction.fill · DataTransaction.id · DataTransaction.resize · DataTransaction.set_attr · DataTransaction.set_attrs · DataTransaction.status · DataTransaction.write
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.