What does the `fopen` function do in MATLAB / RunMat?

fopen opens a file and returns a numeric file identifier (fid) that other I/O functions use. It mirrors MATLAB's permissions ('r', 'w', 'a', '+, 'b', 't'), respects machine-format specifiers, and records the text encoding used for subsequent reads and writes.

How does the `fopen` function behave in MATLAB / RunMat?

fid = fopen(filename) opens an existing file for reading. The call fails (returning fid = -1) when the file cannot be opened.
fid = fopen(filename, permission) opens a file using the requested permission string ('r', 'w', 'a', 'r+', 'w+', 'a+', plus optional 'b'/'t'). Permissions map to the same semantics as MATLAB: 'w' truncates, 'a' appends, and '+' enables reading and writing.
fid = fopen(filename, permission, machinefmt, encoding) records the requested machine format ('native', 'ieee-le', 'ieee-be') and text encoding (defaults to UTF-8 in text mode, binary otherwise) for later inspection.
[fid, message] = fopen(...) returns an empty character vector on success and the operating-system error message on failure.
[filename, permission, machinefmt, encodingOut] = fopen(fid) queries an existing file identifier.
[fid_list, names, machinefmts, encodings] = fopen('all') lists every open file (including standard input/output/error) and returns cell arrays containing metadata for each entry.
[fid_list, names] = fopen('all', machinefmt) filters the listing to files whose recorded machine format (for example 'ieee-be' or 'native') matches the requested value.
RunMat gathers GPU-resident filename arguments before opening files; the resulting handles always live on the host. Providers do not implement GPU kernels for file I/O.

Examples of using the `fopen` function in MATLAB / RunMat

Open a File for Reading

[fid, message] = fopen('data/input.txt', 'r');
if fid == -1
    error('Failed to open file: %s', message);
end

Write Text to a New File

[fid, message] = fopen('logs/session.log', 'w');
if fid == -1
    error('Failed to create log file: %s', message);
end
fprintf(fid, 'Session started\n');
fclose(fid);

Append Binary Data

[fid, message] = fopen('signals.bin', 'ab+');
if fid == -1
    error('Failed to open binary log: %s', message);
end
fwrite(fid, rand(1, 1024), 'double');
fclose(fid);

Query File Metadata

fid = fopen('config.json');
[filename, permission, machinefmt, encoding] = fopen(fid);
disp(filename);
disp(permission);
fclose(fid);

List All Open Files

[fid_list, names] = fopen('all');
disp(fid_list);
disp(names);

Handle Missing Files Gracefully

[fid, message] = fopen('does_not_exist.txt', 'r');
if fid == -1
    fprintf('Failed to open file: %s\n', message);
end

Specify Machine Format and Encoding

[fid, message, machinefmt, encoding] = fopen('report.txt', 'w', 'ieee-le', 'latin1');
if fid == -1
    error('Failed to open report: %s', message);
end
fprintf(fid, 'olá mundo');
fclose(fid);

`fopen` GPU Execution Behaviour

fopen always executes on the CPU. When a filename argument resides on a GPU array, RunMat gathers it to host memory before opening the file. File identifiers and their associated metadata are managed by a host-side registry that other builtins (such as fclose, fread, and fwrite) consult.

FAQ

What values can I use for the permission argument?

Use the same strings MATLAB accepts: 'r', 'w', 'a', optionally combined with '+' and 'b'/'t'. For example, 'r+' opens an existing file for reading and writing, 'wb' opens a binary file for writing (truncating any existing content), and 'ab+' appends to a binary file while permitting reads.

How do I close a file after opening it?

Call fclose(fid) with the file identifier returned by fopen. RunMat tracks open handles in a registry so that fclose, fread, and fwrite can reuse the same identifier.

What happens if `fopen` fails?

fopen returns fid = -1 and the second output argument contains the OS error message. The third and fourth outputs are empty character vectors when opening fails.

Which encoding does RunMat use by default?

Text-mode files default to UTF-8 unless you specify the encoding argument. Binary permissions ('...b') implicitly use the pseudo-encoding binary.

Does `fopen('all')` include standard input and output?

Yes. The returned identifier list always contains 0 (standard input), 1 (standard output), and 2 (standard error), followed by any user-opened files.

Are machine formats honoured during reads and writes?

RunMat records the requested machine format so that fread/fwrite can apply byte-order conversions. Hosts default to 'native', while passing 'ieee-le' or 'ieee-be' forces little or big-endian interpretation respectively.

Can I open the same file multiple times?

Yes. Each successful call to fopen registers a new handle with its own identifier, even if the path string matches an existing entry.

Does `fopen` support network paths or UNC shares?

RunMat relies on the operating system for path resolution, so UNC paths and mounted network shares are supported as long as the OS can open them.

Source & Feedback

The implementation lives at crates/runmat-runtime/src/builtins/io/filetext/fopen.rs.
Found a bug or behavioural difference? Open an issue with a repro.

What does the fopen function do in MATLAB / RunMat?

How does the fopen function behave in MATLAB / RunMat?

Examples of using the fopen function in MATLAB / RunMat