dir — Return file and folder metadata in MATLAB and RunMat.
dir returns metadata for files and folders. It supports current-directory listing, explicit paths, and wildcard patterns, returning MATLAB/RunMat-compatible struct fields such as name, folder, date, bytes, isdir, and datenum.
Syntax
listing = dir()
listing = dir(name)
listing = dir(folder, pattern)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
name | StringScalar | Yes | — | Folder, file, or wildcard path to list. |
folder | StringScalar | Yes | — | Base folder to list. |
pattern | StringScalar | Yes | — | Name or wildcard pattern within folder. |
Returns
| Name | Type | Description |
|---|---|---|
listing | Any | Struct array with name/folder/date/bytes/isdir/datenum fields. |
Errors
| Identifier | When | Message |
|---|---|---|
| — | More than two input arguments are provided. | dir: too many input arguments |
| — | Single name argument is not a character vector or string scalar. | dir: name must be a character vector or string scalar |
| — | Folder argument is not a character vector or string scalar. | dir: folder must be a character vector or string scalar |
| — | Pattern argument is not a character vector or string scalar. | dir: pattern must be a character vector or string scalar |
| — | Folder argument contains wildcard characters. | dir: folder input must not contain wildcard characters |
How dir works
dirwith no inputs returns the contents of the current folder (including.and..).- When you call
dirwithout 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)anddir(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 asdd-MMM-yyyy HH:mm:ssin local time.bytes: file size in bytes (0for directories and wildcard-only results).isdir: logical flag indicating whether the entry is a directory.datenum: serial date number compatible with MATLAB'sdatenum.- Results are sorted using MATLAB-style ordering (case-insensitive on Windows, case-sensitive on Unix-like systems).
- Empty matches return a
0×1struct array so idioms likeisempty(dir("*.tmp"))continue working. - Invalid arguments (numeric, logical, non-scalar string arrays) raise MATLAB-compatible diagnostics.
Does RunMat run dir on the GPU?
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 memory and 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
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 % falseList 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.");
endExpected output:
No cache files found.Using dir with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how dir changes the result.
Run a small dir example, explain the result, then change one input and compare the output.
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.
What does dir do in MATLAB?⌄
dir lists files and folders in the current directory. dir(name) lists items matching a file or folder name, which can include wildcards like '*.m'.
How do I list all files in a folder in MATLAB?⌄
Use files = dir('foldername') to get a struct array. Each element has fields name, folder, bytes, isdir, datenum, and date. Filter with files(~[files.isdir]) to exclude folders.
Does dir support recursive search?⌄
Use dir('**/*.m') with the double-star wildcard to recursively find all .m files in subdirectories. This syntax works in RunMat.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · 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 · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how dir is executed, line by line, in Rust.
- View the source for dir 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.