RunMat
GitHub

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

NameTypeRequiredDefaultDescription
fidNumericScalarYes—File identifier opened by fopen.
sizeAnyNo"inf"Element count or size vector ([m n]); supports "inf".
precisionStringScalarNo"double"Read precision label (for example "double", "uint8", "*char").
skipNumericScalarNo0Bytes skipped after each element read.
machinefmtStringScalarNo"native"Machine format label (native/little-endian/big-endian aliases).
precisionStringScalarNo"double"Read precision label when size is omitted.
argAnyVariadic—Positional fread arguments before the like clause.
namePropertyNameNo"like"Prototype keyword; currently only 'like'.
prototypeAnyNo—Prototype value controlling output class/residency.

Returns

NameTypeDescription
dataAnyRead data as numeric tensor or character array depending on precision.

Errors

IdentifierWhenMessage
RunMat:fread:InvalidInputIdentifier/argument cardinality/type constraints are violated.fread: invalid input arguments
RunMat:fread:InvalidIdentifierIdentifier does not refer to a readable open file.fread: invalid file identifier. Use fopen to generate a valid file ID.
RunMat:fread:InvalidOptionPrecision, skip, machine format, or like option values are invalid.fread: invalid option configuration

How fread works

  • A = fread(fid) reads to the end of the file, returning a column vector of doubles.
  • A = fread(fid, sizeA) reads at most prod(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, and char. 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 by fopen.
  • [A, count] = fread(...) returns the number of elements successfully read before encountering EOF.
  • If MATLAB requests more elements than available, fread pads matrix outputs with zeros (or '\0' for character data) to satisfy the requested dimensions; the count output always reflects the number of real elements read from the file.
  • A = fread(___, 'like', prototype) matches the residency and logical or numeric flavour of prototype. GPU prototypes trigger an upload after reading so the result remains on the device, while logical prototypes convert the output using MATLAB's non-zero rule.
  • RunMat executes the builtin entirely on the host CPU. Arguments that reside on a GPU are gathered automatically before any I/O occurs.

Does RunMat run fread on the GPU?

fread is a host-only operation. When the file identifier or optional arguments (size vectors, precision strings, skip counts) live on the GPU, RunMat gathers them to the host first. File handles are managed by the shared registry established by fopen, and GPU providers never participate in file I/O. When a 'like' prototype is a GPU tensor, the builtin uploads the host result after the read so that the output mirrors the prototype's residency. Providers that fail the upload silently fall back to returning the host tensor.

GPU memory and residency

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 on the GPU when an acceleration provider is active. Without a provider the function still returns correct data on the host.

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. Pass a GPU tensor to receive a GPU tensor, use a logical array to obtain logical output (non-zero becomes true), or use a character prototype together with a character precision to obtain a CharArray.

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.

Filetext

fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · frewind · fwrite

Repl Fs

addpath · cd · copyfile · delete · dir · exist · fullfile · genpath · getenv · ls · mkdir · movefile · path · pwd · rmdir · rmpath · run · savepath · setenv · tempdir · tempname

Io

clc · disp · format · input

Mat

load · save

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how fread is executed, line by line, in Rust.

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.

Getting started · Benchmarks · Pricing

Download RunMat

Download RunMat for full performance, or use RunMat in your browser for zero setup.

Download RunMatTry in your browser