RunMat
GitHub

View all functions

CategoryIo: Repl Fs

dir — Return file and folder information in a MATLAB-compatible struct array.

dir returns metadata for files and folders. Without arguments, it lists the current working directory. With an argument, it can list a specific directory, match wildcard patterns, or report information about a single file. The result is a column vector of structs matching MATLAB's signature: each element contains name, folder, date, bytes, isdir, and datenum fields.

How does the dir function behave in MATLAB / RunMat?

  • dir with no inputs returns the contents of the current folder (including . and ..).
  • When you call dir without capturing the output, RunMat prints the listing in the REPL. Assigning the result to a variable suppresses the listing and returns the struct array.
  • dir(path) accepts absolute or relative paths, character vectors, or string scalars. When the path names a directory, its contents are listed; when it names a file, metadata for that file alone is returned.
  • dir(pattern) and dir(folder, pattern) support wildcard expansion with * and ?. Patterns are evaluated relative to the supplied folder or the current working directory.
  • The returned struct fields mirror MATLAB:
  • name: file or folder name.
  • folder: absolute path to the containing folder.
  • date: last-modified timestamp formatted as dd-MMM-yyyy HH:mm:ss in local time.
  • bytes: file size in bytes (0 for directories and wildcard-only results).
  • isdir: logical flag indicating whether the entry is a directory.
  • datenum: serial date number compatible with MATLAB's datenum.
  • Results are sorted using MATLAB-style ordering (case-insensitive on Windows, case-sensitive on Unix-like systems).
  • Empty matches return a 0×1 struct array so idioms like isempty(dir("*.tmp")) continue working.
  • Invalid arguments (numeric, logical, non-scalar string arrays) raise MATLAB-compatible diagnostics.

GPU behavior

Because dir interacts with the host filesystem, it is executed entirely on the CPU. If an input argument resides on the GPU (for example, a scalar string created by another accelerated builtin), RunMat gathers it to host memory before expanding patterns. Acceleration providers do not implement hooks for dir, and the result always lives on the host.

GPU residency

No. dir is an I/O-bound builtin and always operates on host data. Passing GPU-resident strings is supported, but RunMat gathers them automatically and there is no benefit to manually calling gpuArray.

Examples of using dir in MATLAB / RunMat

List Files In The Current Folder

fid = fopen("README.md", "w"); fclose(fid);
mkdir("src");
listing = dir;
{listing.name}

Expected output:

{'.'}    {'..'}    {'README.md'}    {'src'}

List Only MATLAB Files Using Wildcards

fid = fopen("solver.m", "w"); fclose(fid);
fid = fopen("test_helper.m", "w"); fclose(fid);
scripts = dir("*.m");
cellstr({scripts.name})

Expected output:

{'solver.m'}
    {'test_helper.m'}

Capture Metadata For A Specific File

info = dir("data/results.csv");
info.bytes    % file size in bytes
info.isdir    % false

List The Contents Of A Specific Folder

mkdir("tmp");
fid = fopen(fullfile("tmp", "tmpfile.txt"), "w"); fclose(fid);
mkdir(fullfile("tmp", "subdir"));
tmp = dir(fullfile(pwd, "tmp"));
{tmp.name}'

Expected output:

'.'    '..'    'tmpfile.txt'    'subdir'

Combine Folder And Pattern Arguments

mkdir("assets");
fid = fopen(fullfile("assets", "logo.png"), "w"); fclose(fid);
fid = fopen(fullfile("assets", "splash.png"), "w"); fclose(fid);
images = dir("assets", "*.png");
{images.name}

Expected output:

{'logo.png'}    {'splash.png'}

Use Tilde Expansion For Home Directory

home_listing = dir("~")

Expected output:

home_listing(1).folder
ans =
    '/'

Handle Missing Matches Gracefully

if isempty(dir("*.cache"))
    disp("No cache files found.");
end

Expected output:

No cache files found.

FAQ

What types can I pass to dir?

Character vectors or string scalars. Other types (numeric, logical, multi-element string arrays, or cells) raise an error.

Does dir support recursive wildcards?

Yes. Patterns such as "**/*.m" are honoured through the standard globbing rules.

Why do I see . and .. entries?

MATLAB includes them for directory listings; RunMat mirrors this behaviour so scripts relying on their presence continue to work.

What is the datenum field?

A MATLAB serial date number representing the last modification time in local time. Use datetime([entry.datenum]) to convert multiple entries.

Are symbolic links distinguished from folders?

Symlinks are reported using the metadata provided by the operating system. If the link targets a directory, isdir is true.

Can I pass GPU-resident strings?

Yes, but RunMat gathers them automatically before computing the directory listing.

How are errors reported?

Error messages are prefixed with dir: and match MATLAB's argument diagnostics wherever possible.

See also

ls, pwd, cd

Source & Feedback