whos — List workspace or MAT-file variables with MATLAB-compatible metadata fields.
whos returns MATLAB-style variable metadata (name, size, bytes, class, flags) for current workspace values or MAT-file contents.
Syntax
whos(selector, ...) [discarded output]
vars = whos()
vars = whos(selector, ...)
vars = whos("-file", filename, selector, ...)
vars = whos("-regexp", pattern, ...)Inputs
selector- Type
StringScalar- Required
- Variadic
- Description
- Name filters, wildcard patterns, or options.
file_kw- Type
StringScalar- Required
- Yes
- Default
"-file"- Description
- File mode option.
filename- Type
StringScalar- Required
- Yes
- Description
- MAT-file path.
regexp_kw- Type
StringScalar- Required
- Yes
- Default
"-regexp"- Description
- Regexp mode option.
pattern- Type
StringScalar- Required
- Variadic
- Description
- Regular-expression patterns.
Returns
vars- Type
Any- Description
- Structure array describing matching variables.
Errors
- When
- The '-file' option is provided without a filename.
- Message
whos: '-file' requires a filename
- When
- The '-file' option is provided more than once.
- Message
whos: '-file' may only be specified once
- When
- The '-regexp' option is provided without patterns.
- Message
whos: '-regexp' requires at least one pattern
Behavior
whos with no arguments lists every variable in the active workspace, using MATLAB's default alphabetical ordering.
whos pattern1 pattern2 ... accepts character vectors or string scalars containing wildcard expressions (*, ?, [abc]). Any variable whose name matches at least one pattern is reported.
whos('-regexp', expr1, expr2, ...) keeps variables whose names match any of the supplied regular expressions.
whos global lists only the variables that are marked as global within the active workspace.
whos('-file', filename, ...) reads and decodes MAT-file values through the existing MAT reader, without assigning them to the workspace. It is not a metadata-only partial-file scan.
The returned struct array uses string scalars for textual fields (name, class, nesting) and MATLAB-style numeric row vectors for the size field.
bytes reports the amount of memory consumed by the value using RunMat's host representation. GPU arrays stay on the device; RunMat estimates bytes from the device-resident shape and provider precision.
Residency and execution
Workspace GPU values are inspected from shape and physical element metadata; their payloads are not gathered. Numeric resident selectors are invalid and reject before provider readback. Record size/bytes are RunMat presentation doubles, not an exact wide-integer carrier.
You do not need to move data to or from the GPU to call whos. Numeric resident selector arguments reject before readback; workspace variables remain where they are. Use gather separately if you need host copies of the data for further processing.
whos is an introspection builtin that runs entirely on the CPU. When a variable is a gpuArray, RunMat leaves it on the device and derives metadata (element count, precision, and total bytes) from the admitted handle metadata. No kernels are launched and no device buffers are gathered. Auto-offload heuristics remain untouched.
Legacy examples and displayed results
List All Workspace Variables
a = 42;
b = rand(3, 2);
info = whos;
{info.name}
Expected display: {"a"} {"b"}
Filter Variables With Wildcards
alpha = 1;
beta = 2;
results = whos("a*");
{results.name}
Expected display: {"alpha"}
Use Regular Expressions To Match Names
x1 = rand;
x2 = rand;
matches = whos('-regexp', '^x\\d$');
cellstr({matches.name})
Expected display: {'x1'}
{'x2'}
Inspect Variables Stored In A MAT-File
save('snapshot.mat', 'alpha', 'beta')
file_info = whos('-file', 'snapshot.mat');
{file_info.name}
Expected display: {"alpha"} {"beta"}
Check GPU Arrays Without Gathering
G = gpuArray(rand(1024));
meta = whos('G');
meta.bytes % estimated bytes on device
Expected display: meta.bytes
ans =
8.3886e+06
Examples
Inspect one workspace value
alpha = uint64(7); beta = 2; info = whos("a*"); {info.name}Read metadata from a MAT-file
alpha = uint64(7); beta = 2; save('workspace_meta_snapshot.mat','alpha','beta'); file_info = whos('-file','workspace_meta_snapshot.mat'); {file_info.name}Inspect a resident value without gathering
G = gpuArray([1 2; 3 4]); meta = whos('G'); meta.bytesUsing whos with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how whos changes the result.
Run a small whos example, explain the result, then change one input and compare the output.
FAQ
What fields does whos return?⌄
Each entry exposes name, size, bytes, class, global, sparse, complex, nesting, and persistent, matching MATLAB semantics.
Does whos mutate the workspace?⌄
No. It is a read-only query; the -file form does perform filesystem reads, but neither form creates, deletes, or modifies workspace variables.
Are bytes identical to MATLAB?⌄
RunMat reports the size of its own representations. Numeric and logical arrays match MATLAB's byte counts; other types (such as structs or objects) may differ slightly because RunMat records their data differently.
How are global variables handled?⌄
Variables declared with global are marked with global = true. Use whos global to list only globals.
Can I combine wildcard filters and -regexp?⌄
Yes. whos('data*', '-regexp', '^(cfg|state)') reports the union of both selections.
What happens when no variables match?⌄
A 0×1 struct array is returned, just like MATLAB, so idioms such as isempty(whos('foo')) work.
Does whos('-file', ...) read the entire MAT-file?⌄
The current MAT reader decodes file content to reconstruct values, without assigning them to the workspace. It is not a metadata-only partial-file scan.
How are persistent variables reported?⌄
RunMat currently marks all entries as persistent = false in the base workspace. Future releases will surface persistent metadata from function scopes.
Will GPU arrays be gathered?⌄
No. whos inspects device handles and leaves residency untouched.
Related Introspection functions
addlistener · addParameter · addprop · assignin · builtin · cancel · class · clear · clearAllMemoizedCaches · clearCache · clearvars · dbclear · dbstack · dbstatus · dbtype · eval · evalc · evalin · feval · findprop · func2str · functions · get.p · getcallinfo · getmethod · inputname · inputParser · isa · ischar · isdeployed · iskeyword · ismethod · isobject · isstring · isUnderlyingType · isvalid · keyboard · loadobj · localfunctions · matlab.metadata.DynamicProperty.delete · memoize · metaclass · mfilename · mislocked · mlock · munlock · namelengthmax · narginchk · nargoutchk · new_object · notify · numArgumentsFromSubscript · onCleanup · parse · saveobj · set.p · stats · str2func · subsasgn · subsref · superclasses · underlyingType · verLessThan · version · which · who
Source you can read
Every RunMat function's source is public. Read exactly how whos is executed, line by line, in Rust.
- View the source for whos 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.