What does the fclose function do in MATLAB / RunMat?

fclose closes files that were previously opened with fopen. Pass a file identifier, an array of identifiers, or the keyword 'all' to close the desired handles. The first output (status) is 0 when the close succeeds and -1 otherwise. The optional second output (message) contains diagnostic text when an identifier is invalid.

How does the fclose function behave in MATLAB / RunMat?

• status = fclose(fid) closes the file represented by the numeric identifier fid. The status is 0 on success and -1 if the identifier is invalid.
• status = fclose([fid1 fid2 ...]) closes a vector of identifiers. If any identifier is invalid, status is -1 and message explains the failure.
• status = fclose('all') (or fclose() with no arguments) closes every open file except the standard streams (0, 1, 2).
• [status, message] = fclose(...) returns the diagnostic message. On success, message is an empty character vector.
• Identifiers 0, 1, and 2 refer to standard input, output, and error. fclose treats them as already-open handles and simply returns success.
• RunMat keeps file metadata in a registry shared with fopen, ensuring MATLAB-compatible behaviour across subsequent I/O builtins.

Examples of using the fclose function in MATLAB / RunMat

Close a file after writing data

[fid, msg] = fopen('results.txt', 'w');
if fid == -1
    error('Failed to open file: %s', msg);
end
fprintf(fid, 'Simulation complete\n');
status = fclose(fid);

Expected output:

status = 0;

Close all open files at once

% Close every file except stdin/stdout/stderr
status = fclose('all');

Expected output:

status = 0;

Handle invalid file identifiers gracefully

[status, message] = fclose(9999);
if status == -1
    fprintf('Close failed: %s\n', message);
end

Expected output:

status = -1;
message = 'Invalid file identifier. Use fopen to generate a valid file ID.';

Close multiple file identifiers together

fids = fopen('all');
status = fclose(fids);

Expected output:

status = 0;

Detect failures with the second output

[fid, msg] = fopen('data.bin', 'r');
assert(fid ~= -1, msg);
fclose(fid);
[status, message] = fclose(fid);  % closes again, returns -1 and an error string

Expected output:

status = -1;
message = 'Invalid file identifier. Use fopen to generate a valid file ID.';

Close files using the no-argument form

% Equivalent to fclose('all')
status = fclose();

Expected output:

status = 0;

fclose GPU Execution Behaviour

fclose does not perform GPU computation. If the argument resides on a GPU array (for example, 'all' stored in a gpuArray), RunMat gathers the value to host memory before dispatching the host-only close logic.

FAQ

What values can I pass to fclose?

Pass a numeric file identifier (scalar or array) returned by fopen, or the keyword 'all'. Calling fclose() with no arguments is equivalent to fclose('all').

What does the status code mean?

0 indicates that every requested identifier was successfully processed. -1 means that at least one identifier was invalid; the optional second output contains the diagnostic message.

Does fclose close standard input/output?

Identifiers 0, 1, and 2 always refer to the process standard streams. fclose accepts them but leaves the streams open, returning a success status.

Can I call fclose multiple times on the same identifier?

Yes. The first call closes the file and subsequent calls return status -1 with the message "Invalid file identifier. Use fopen to generate a valid file ID."

Does fclose flush buffered writes?

Closing a file flushes buffered writes and releases the underlying operating system descriptor, matching MATLAB behaviour.

Do I need to close files explicitly when using GPU arrays?

Yes. GPU residency does not change the lifecycle of file handles. Use fclose to release identifiers created with fopen regardless of where the arguments reside.

Can fclose close files opened by other processes?

No. It only closes identifiers that the current RunMat process opened via fopen.

See Also

fopen, fread, fwrite, fileread, filewrite

Source & Feedback

• The implementation lives at crates/runmat-runtime/src/builtins/io/filetext/fclose.rs.
• Found a behavioural mismatch? Open an issue with a minimal repro.