RunMat
GitHub

View all functions

CategoryIo: Repl Fs

movefile — Move or rename files and folders with MATLAB-compatible status, message, and message ID outputs.

movefile renames files and folders or moves them to a new location. It mirrors MATLAB by returning status information instead of throwing errors for filesystem failures and by accepting the optional 'f' flag to overwrite destinations.

How does the movefile function behave in MATLAB / RunMat?

  • status = movefile(source, destination) moves or renames source. status is a double scalar that is 1 on success and 0 on failure.
  • [status, message, messageID] = movefile(...) also returns MATLAB-style diagnostic text. Successful operations populate both strings with empty character arrays (1×0).
  • movefile(source, destination, 'f') forces the move, overwriting an existing destination file or folder. Without the flag, movefile refuses to overwrite existing targets.
  • Wildcards in source (such as *.m) expand to matching filesystem entries. When the pattern resolves to multiple items, destination must be an existing folder and movefile moves each match into that folder.
  • Inputs accept character vectors or string scalars. Other types raise MATLAB-style errors before any filesystem work occurs.
  • Paths are resolved relative to the current working directory (pwd) and expand a leading ~ into the user's home directory.
  • Filesystem failures—including missing files, permission errors, or read-only destinations—return status = 0 plus descriptive diagnostics; only invalid inputs raise immediate errors.

GPU behavior

movefile performs host-side filesystem operations. When acceleration providers are active, RunMat first gathers any GPU-resident arguments (for example, gpuArray("logs")), executes the move on the CPU, and returns host-resident outputs. Providers do not expose special hooks for this builtin, so GPU execution is not applicable.

GPU residency

No. movefile always runs on the host CPU, so storing paths on the GPU offers no benefit. If a string argument is already GPU-resident, RunMat gathers it automatically before touching the filesystem so existing scripts continue to work unchanged.

Examples of using movefile in MATLAB / RunMat

Rename a file in the same folder

fid = fopen("results.txt", "w"); fclose(fid);
status = movefile("results.txt", "archive.txt")

Expected output:

status =
     1

Move a file into an existing folder

mkdir("reports");
fid = fopen("summary.txt", "w"); fclose(fid);
status = movefile("summary.txt", "reports")

Expected output:

status =
     1

Force overwrite an existing destination

fid = fopen("draft.txt", "w"); fclose(fid);
fid = fopen("final.txt", "w"); fclose(fid);
[status, message, messageID] = movefile("draft.txt", "final.txt", "f")

Expected output:

status =
     1
message =

messageID =

Move multiple files with a wildcard

mkdir("data");
fid = fopen("a.log", "w"); fclose(fid);
fid = fopen("b.log", "w"); fclose(fid);
status = movefile("*.log", "data")

Expected output:

status =
     1

Handle missing sources gracefully

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

Expected output:

status =
     0
message =
Source "missing.txt" does not exist.
messageID =
MATLAB:MOVEFILE:FileDoesNotExist

Use gpuArray inputs for paths

fid = fopen("draft.txt", "w"); fclose(fid);
status = movefile(gpuArray("draft.txt"), gpuArray("final.txt"))

Expected output:

status =
     1

FAQ

What status codes does movefile return?

1 indicates every requested move succeeded; 0 indicates that nothing was moved. Status values are doubles so existing MATLAB scripts continue to work.

Does movefile throw exceptions?

Only invalid inputs raise errors. Filesystem failures surface through the status, message, and message ID outputs.

How do I overwrite an existing file?

Pass the 'f' flag as the third argument. Without it, movefile refuses to overwrite existing files or folders.

Can I move multiple files at once?

Yes. Include wildcards such as *.txt in source. The destination must be an existing folder in that case.

Does movefile work with folders?

Yes. It can move or rename entire folders. When moving into another folder and the target name already exists, pass 'f' to overwrite it.

How are paths resolved?

Paths are resolved relative to pwd, and a leading ~ expands to the user's home directory.

Will GPU acceleration speed up movefile?

No. The builtin executes on the host CPU. GPU-resident strings are gathered automatically before performing the move.

What happens if no files match a wildcard?

The function returns status = 0, sets message to "Source \"pattern\" does not exist.", and leaves the filesystem unchanged.

Does the function preserve timestamps or permissions?

Yes. movefile forwards the operation to the operating system, which preserves attributes when possible.

Can I move directories across volumes?

When the underlying operating system reports an error (for example, moving across volumes without rename support), movefile returns status = 0 along with the system error text so you can handle it programmatically.

See also

copyfile, mkdir, rmdir, dir, pwd

Source & Feedback