fread — Read binary data from file identifiers in MATLAB and RunMat.
fread reads binary data from a file identifier returned by fopen. Size, precision, skip, and machine-format arguments follow MATLAB semantics, and file position advances accordingly. Optional second output returns the number of elements successfully read.
Syntax
data = fread(fid)
data = fread(fid, size)
data = fread(fid, size, precision)
data = fread(fid, size, precision, skip)
data = fread(fid, size, precision, skip, machinefmt)
data = fread(fid, precision)All supported fread forms
data = fread(fid)
data = fread(fid, size)
data = fread(fid, size, precision)
data = fread(fid, size, precision, skip)
data = fread(fid, size, precision, skip, machinefmt)
data = fread(fid, precision)
data = fread(fid, precision, skip)
data = fread(fid, precision, machinefmt)
data = fread(fid, precision, skip, machinefmt)
data = fread(fid, ..., "like", prototype)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
fid | NumericScalar | Yes | — | File identifier opened by fopen. |
size | Any | No | "inf" | Element count or size vector ([m n]); supports "inf". |
precision | StringScalar | No | "uint8=>double" | Read precision label (for example "double", "uint8", "*char"). |
precision | StringScalar | No | "double" | Read precision label (for example "double", "uint8", "*char"). |
skip | NumericScalar | No | 0 | Bytes skipped after each element read. |
machinefmt | StringScalar | No | "native" | Machine format label (native/little-endian/big-endian aliases). |
precision | StringScalar | No | "double" | Read precision label when size is omitted. |
arg | Any | Variadic | — | Positional fread arguments before the like clause. |
name | PropertyName | No | "like" | Prototype keyword; currently only 'like'. |
prototype | Any | No | — | Prototype value controlling output class/residency. |
Returns
| Name | Type | Description |
|---|---|---|
data | Any | Read data as numeric tensor or character array depending on precision. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:fread:InvalidInput | Identifier/argument cardinality/type constraints are violated. | fread: invalid input arguments |
RunMat:fread:InvalidIdentifier | Identifier does not refer to a readable open file. | fread: invalid file identifier. Use fopen to generate a valid file ID. |
RunMat:fread:InvalidOption | Precision, skip, machine format, or like option values are invalid. | fread: invalid option configuration |
RunMat:fread:IoFailure | Read/seek or data-shape materialization fails. | fread: file read failed |
| — | Internal runtime control-flow conversion failed. | fread: internal error |
How fread works
A = fread(fid)readsuint8source values to the end of the file and returns a double column vector, including a0-by-1column for an empty read.A = fread(fid, sizeA)reads at mostprod(sizeA)elements, filling the result in column-major order. Use[m n]to request a matrix or[m Inf]to keep filling columns until EOF.A = fread(fid, precision)controls how many bytes each element consumes and how the result is typed. RunMat supports the common precisions from MATLAB:double,single,uint8,int8,uint16,int16,uint32,int32,uint64,int64, andchar. When no output class is specified, data is converted to double;char(and*char) return a MATLAB-style character array.A = fread(fid, sizeA, precision, skip, machinefmt)honours optional byte skipping and machine-format overrides ('native','ieee-le','ieee-be'). The machine format defaults to the value recorded byfopen.[A, count] = fread(...)returns the number of elements successfully read before encountering EOF.- If MATLAB requests more elements than available,
freadpads matrix outputs with zeros (or'\0'for character data) to satisfy the requested dimensions; thecountoutput always reflects the number of real elements read from the file. - In
runmatcompatibility mode,A = fread(___, 'like', prototype)is a RunMat extension that matches the residency and logical or numeric flavour ofprototype. All eight typed integer prototype classes determine exact saturating output storage. GPU prototypes upload through their actual owning provider after pre-read metadata validation, while logical prototypes convert the output using the ordinary non-zero rule. Character precision requires a character prototype, and character prototypes require character precision; invalid pairings reject before file access. - RunMat executes the builtin entirely on the host CPU. Typed integer file identifiers, sizes, and skips are independent RunMat extensions, as are logical, single, and provider-resident controls; all extension policy is checked before gather or I/O.
Does RunMat run fread on the GPU?
fread is a host-only operation. In runmat compatibility mode, independently gated resident controls gather before host I/O, and the separately gated 'like' form can upload the result to a GPU prototype. File handles remain in the shared host registry.
GPU memory and residency
In runmat compatibility mode, the RunMat-only 'like' form can upload the result to match a GPU prototype:
fid = fopen('samples.bin', 'w+b');
fwrite(fid, [2.5 4.5 6.5 8.5], 'double');
frewind(fid);
prototype = gpuArray.zeros(4, 1);
[values, count] = fread(fid, 4, 'double', 'like', prototype);
% When a GPU provider is active, values stays on the GPU and count == 4.
fclose(fid);
delete('samples.bin');values stays with the prototype's owning provider. A missing or malformed owner contract rejects before reading rather than silently returning host data.
Examples
Reading double-precision values from a binary file
fid = fopen('numbers.bin', 'w+b');
fwrite(fid, [1 2 3], 'double');
frewind(fid);
[values, count] = fread(fid); % defaults to double precision
% values is a 3x1 column vector [1; 2; 3], count == 3
fclose(fid);
delete('numbers.bin')Reading bytes with a specific element count
fid = fopen('payload.bin', 'w+b');
fwrite(fid, uint8(1:6), 'uint8');
frewind(fid);
[bytes, count] = fread(fid, 4, 'uint8');
% bytes == [1; 2; 3; 4], count == 4
fclose(fid);
delete('payload.bin')Loading a two-dimensional block of uint8 data
fid = fopen('frame.bin', 'w+b');
payload = uint8(reshape(1:12, 3, 4));
fwrite(fid, payload, 'uint8');
frewind(fid);
[frame, count] = fread(fid, [3 4], 'uint8');
frame = uint8(frame); % convert back to uint8 if needed
fclose(fid);
delete('frame.bin')Reading characters using the *char precision form
fid = fopen('message.txt', 'w+b');
fwrite(fid, 'RunMat', 'char');
frewind(fid);
[text, count] = fread(fid, '*char');
text = text.'; % row string 'RunMat'
fclose(fid);
delete('message.txt')Skipping bytes between samples
fid = fopen('interleaved.bin', 'w+b');
fwrite(fid, uint8(1:12), 'uint8');
frewind(fid);
[every_other, count] = fread(fid, 5, 'uint8', 1); % read one byte, skip one byte
% every_other == [1; 3; 5; 7; 9]
fclose(fid);
delete('interleaved.bin')Respecting big-endian machine formats
fid = fopen('sensors.be', 'w+b', 'ieee-be');
fwrite(fid, uint16([258 772]), 'uint16');
frewind(fid);
[values, count] = fread(fid, [2 1], 'uint16');
% values == [258; 772], count == 2
fclose(fid);
delete('sensors.be')Matching GPU residency with 'like'
fid = fopen('samples.bin', 'w+b');
fwrite(fid, [2.5 4.5 6.5 8.5], 'double');
frewind(fid);
prototype = gpuArray.zeros(4, 1);
[values, count] = fread(fid, 4, 'double', 'like', prototype);
% When a GPU provider is active, values stays on the GPU and count == 4.
fclose(fid);
delete('samples.bin')Using fread with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how fread changes the result.
Run a small fread example, explain the result, then change one input and compare the output.
FAQ
What precision strings are supported?⌄
RunMat implements the commonly used MATLAB precisions: double, single, uint8, int8, uint16, int16, uint32, int32, uint64, int64, and char. The short form *char is also recognised. When an output class is not specified explicitly (with => or the *class syntax), the result is converted to double precision.
How are partial reads handled?⌄
fread stops when it encounters EOF. Matrices requested with [m n] are padded with zeros (or '\0') when the file does not contain enough elements to fill every column. The count output records the number of real elements read before padding.
How do size arguments work?⌄
Pass a scalar N to request a column vector with up to N elements, [M N] to request a matrix with M rows and N columns, or [M Inf] to keep reading additional columns until EOF. Omitting the size argument is equivalent to using Inf (read everything).
How does the skip parameter behave?⌄
skip specifies the number of bytes to skip after reading each element. It must be a non-negative integer. The file position advances by the element size plus the skip value for every element that is successfully read.
What does the 'like' prototype control?⌄
The 'like', prototype pair matches the output residency and high-level type of prototype. All eight typed integer classes select exact saturating output storage. A GPU tensor returns through its owning provider, a logical prototype applies the non-zero rule, and only a character prototype may accompany character output precision.
Which machine formats are supported?⌄
The builtin recognises 'native', 'ieee-le', and 'ieee-be' (including their MATLAB aliases such as 'little-endian', 'pc', 'big-endian', and 'mac'). Unsupported formats ('vaxd', 'cray', etc.) raise descriptive errors.
Can fread operate on standard input?⌄
Standard input/output/error identifiers (0, 1, 2) are currently not supported by RunMat's fread. Open files explicitly with fopen before calling fread.
Related Io functions
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · frewind · fwrite · readlines · writelines
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 · uiputfile · 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
Import
Json
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how fread is executed, line by line, in Rust.
- View the source for fread 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.