uiputfile — Open a host save-file dialog and return the selected file name and path.
uiputfile requests a save-file target from the active RunMat filesystem provider and returns MATLAB-compatible output values. Interactive hosts can implement the provider hook to show a native or browser save picker; noninteractive hosts return the standard cancellation values.
Syntax
file = uiputfile()
file = uiputfile(filter)
[file, path] = uiputfile(filter, title)
[file, path, index] = uiputfile(filter, title, defaultName)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filter | Any | No | "*.*" | File extension pattern, semicolon-delimited patterns, or an N-by-1/N-by-2 cell array of patterns and descriptions. |
title | StringScalar | No | — | Dialog title. |
defaultName | StringScalar | No | — | Initial file or directory path for the dialog. |
Returns
| Name | Type | Description |
|---|---|---|
file | Any | Selected filename, or 0 when cancelled. |
path | Any | Directory containing the selected file, including a trailing separator, or 0 when cancelled. |
index | NumericScalar | One-based selected filter index, or 0 when cancelled. |
Returned values from uiputfile depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:uiputfile:InvalidArgument | A filter, title, or default path has an unsupported type or shape. | uiputfile: invalid argument |
RunMat:uiputfile:TooManyOutputs | More than three output arguments are requested. | uiputfile: too many output arguments |
RunMat:uiputfile:HostError | The active filesystem provider fails while opening the host save-file UI. | uiputfile: file selection failed |
RunMat:uiputfile:InvalidSelection | The active filesystem provider returns a malformed save-file selection. | uiputfile: invalid file selection |
How uiputfile works
file = uiputfile()uses an all-files filter.uiputfile(filter)accepts a character vector, string scalar, semicolon-delimited pattern list, or an N-by-1/N-by-2 cell array of patterns and descriptions.uiputfile(filter, title, defaultName)forwards the dialog title and initial file or directory path to the filesystem provider.- The selected
pathoutput is the containing directory with a trailing path separator. Theindexoutput is a one-based integer-valued double, not a native integer-class result. - Inputs are textual. Host or provider-resident numeric values are rejected before the save-file request is made.
- Cancellation returns numeric zero for
file,path, andindex, matching MATLAB. This is also the behavior for filesystem providers that do not implement a save-file picker.
GPU memory and residency
No. Save-file dialogs are host/UI operations and always execute outside GPU residency. The provider hook returns a path in the active filesystem namespace, so browser hosts should map save targets into the mounted provider namespace before returning the path.
Examples
Choose A MAT-File Destination
[file, path] = uiputfile('*.mat', 'Save workspace');
if isequal(file, 0)
return;
end
save(fullfile(path, file));Use Multiple Filters
filters = {'*.mat', 'MAT-files'; '*.txt', 'Text files'};
[file, path, index] = uiputfile(filters, 'Export data', 'results.mat');Using uiputfile with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how uiputfile changes the result.
Run a small uiputfile example, explain the result, then change one input and compare the output.
FAQ
What happens in noninteractive or headless RunMat hosts?⌄
RunMat returns the MATLAB cancellation values (0) unless the active filesystem provider implements selectFileSave / select_file_save.
How does a browser host provide a real save picker?⌄
Install a filesystem provider with a selectFileSave(request) function. Return null or false for cancellation, a string path for one file, or an object such as { path: '/data/results.mat', filterIndex: 1 }.
Does uiputfile write the selected file?⌄
No. It only returns the selected file name and directory. Use fullfile(path, file) with save, fopen, writematrix, or another file-writing builtin to create the file.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · 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 · 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 uiputfile is executed, line by line, in Rust.
- View the source for uiputfile 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.