frewind — Rewind file position indicators in MATLAB and RunMat.
frewind(fid) resets the file position indicator to the beginning of the file associated with fid. It is equivalent to fseek(fid, 0, 'bof') and follows MATLAB and RunMat status/error semantics.
Syntax
frewind(fid)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
fid | NumericScalar | Yes | — | File identifier opened by fopen. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:frewind:InvalidInput | Input identifier is malformed or out of range. | frewind: invalid input arguments |
RunMat:frewind:InvalidIdentifier | Identifier does not refer to an open file handle. | frewind: invalid file identifier. Use fopen to generate a valid file ID. |
RunMat:frewind:IoFailure | Underlying seek/rewind operation fails. | frewind: file I/O failed |
| — | Internal runtime control-flow or conversion failed. | frewind: internal error |
How frewind works
frewind(fid)rewinds the file position indicator to byte offset 0 for the file identified byfid.fidmust be a non-negative integer returned byfopen. Passing an invalid identifier raises an error.- Standard input/output identifiers (
0,1,2) are silently accepted and treated as a no-op; RunMat does not support seeking on those streams. frewindproduces no output value. Assigning the result offrewindto a variable yields an empty output list.- After
frewind, subsequent calls tofread,fgets, orfscanfstart from the beginning of the file.
Does RunMat run frewind on the GPU?
frewind is a host-only operation. If fid resides on the GPU (for example inside a gpuArray), RunMat gathers the scalar to host memory before consulting the file registry. File handles always remain on the CPU, so there are no provider hooks or fusion paths for this builtin.
GPU memory and residency
No. File identifiers are always owned by the host-side registry maintained by fopen. Wrapping a scalar identifier in gpuArray does not keep the file handle on the GPU—the runtime gathers the scalar before performing the seek. The rewind operation itself executes entirely on the host.
Examples
Write then rewind and read back binary data
fid = fopen('data.bin', 'w+b');
fwrite(fid, [1 2 3], 'double');
frewind(fid);
values = fread(fid, 'double');
fclose(fid);
delete('data.bin')Read a text file twice without reopening
fid = fopen('notes.txt', 'r');
first_line = fgets(fid);
frewind(fid);
same_line = fgets(fid);
fclose(fid)Rewind a binary file opened for reading bytes
fid = fopen('payload.bin', 'w+b');
fwrite(fid, uint8(1:6), 'uint8');
frewind(fid);
bytes = fread(fid, 4, 'uint8');
fclose(fid);
delete('payload.bin')Using frewind with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how frewind changes the result.
Run a small frewind example, explain the result, then change one input and compare the output.
FAQ
What kind of input does frewind accept?⌄
Pass a scalar numeric file identifier returned by fopen. The identifier must be a non-negative integer. Character vectors and strings are not accepted.
Does frewind return a value?⌄
No. frewind is a void function and produces no output. Capturing its result assigns an empty output list.
How does frewind compare to fseek?⌄
frewind(fid) is exactly equivalent to fseek(fid, 0, 'bof'). Use frewind when you only ever need to return to the beginning; use fseek when you need to jump to arbitrary positions.
Can I call frewind on a write-only file?⌄
Yes, as long as the underlying file was opened with a mode that supports seeking (e.g. 'w+' or 'w+b'). Rewinding a write-only stream positions the cursor at the start so subsequent writes overwrite from the beginning.
Can I call frewind on a closed file?⌄
No. Passing a closed or never-opened identifier raises "Invalid file identifier. Use fopen to generate a valid file ID."
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fullfile · genpath · getenv · ls · mkdir · movefile · path · pwd · rmdir · rmpath · run · savepath · setenv · tempdir · tempname · uigetfile · uiputfile
Tabular
csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · readmatrix · spreadsheetImportOptions · writecell · writematrix · xlsread
Import
Json
Archive
Http
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how frewind is executed, line by line, in Rust.
- View the source for frewind 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.