fread

Read data from binary file

Syntax

A = fread(fileID)

A = fread(fileID,sizeA)

A = fread(fileID,precision)

A = fread(fileID,sizeA,precision)

A = fread(___,skip)

A = fread(___,machinefmt)

[A,count] = fread(___)

Description

A = fread(fileID) reads data from an open binary file into column vector A and positions the file pointer at the end-of-file marker. The binary file is indicated by the file identifier, fileID. Use fopen to open the file and obtain the fileID value. When you finish reading, close the file by calling fclose(fileID).

A = fread(fileID,sizeA) reads file data into an array, A, with dimensions, sizeA, and positions the file pointer after the last value read. fread populates A in column order.

A = fread(fileID,precision) interprets values in the file according to the form and size described by precision.

A = fread(fileID,sizeA,precision) reads file data into an array, A, with dimensions, sizeA, and positions the file pointer after the last value read. fread populates A in column order. Values are interpreted in the file according to the form and size described by precision.

A = fread(___,skip) skips the number of bytes or bits specified by skip after reading each value in the file.

A = fread(___,machinefmt) additionally specifies the order for reading bytes or bits in the file.

[A,count] = fread(___) additionally returns the number of characters that fread reads into A. You can use this syntax with any of the input arguments of the previous syntaxes.

Examples

Read Entire File of uint8 Data

Write a nine-element vector to a sample file, nine.bin.

fileID = fopen('nine.bin','w');
fwrite(fileID,[1:9]);
fclose(fileID);

Read all the data in the file into a vector of class double. By default, fread reads a file 1 byte at a time, interprets each byte as an 8-bit unsigned integer (uint8), and returns a double array.

fileID = fopen('nine.bin');
A = fread(fileID)

A = 9×1

     1
     2
     3
     4
     5
     6
     7
     8
     9

fread returns a column vector, with one element for each byte in the file.

View information about A.

whos A

  Name      Size            Bytes  Class     Attributes

  A         9x1                72  double              

Close the file.

fclose(fileID);

Read Entire File of Double-Precision Data

Create a file named doubledata.bin, containing nine double-precision values.

fileID = fopen('doubledata.bin','w');
fwrite(fileID,magic(3),'double');
fclose(fileID);

Open the file, doubledata.bin, and read the data in the file into a 3-by-3 array, A. Specify that the source data is class double.

fileID = fopen('doubledata.bin');
A = fread(fileID,[3 3],'double')

A = 3×3

     8     1     6
     3     5     7
     4     9     2

Close the file.

fclose(fileID);

Read Selected Rows or Columns from File

Create a file named nine.bin, containing the values from 1 to 9. Write the data as uint16 values.

fileID = fopen('nine.bin','w');
fwrite(fileID,[1:9],'uint16');
fclose(fileID);

Read the first six values into a 3-by-2 array. Specify that the source data is class uint16.

fileID = fopen('nine.bin');
A = fread(fileID,[3,2],'uint16')

A = 3×2

     1     4
     2     5
     3     6

fread returns an array populated column-wise with the first six values from the file, nine.bin.

Return to the beginning of the file.

frewind(fileID)

Read two values at a time, and skip one value before reading the next values. Specify this format using the precision value, '2*uint16'. Because the data is class uint16, one value is represented by 2 bytes. Therefore, specify the skip argument as 2.

precision = '2*uint16';
skip = 2;
B = fread(fileID,[2,3],precision,skip)

B = 2×3

     1     4     7
     2     5     8

fread returns a 2-by-3 array populated column-wise with the values from nine.bin.

Close the file.

fclose(fileID);

Read Digits of Binary Coded Decimal Values

Create a file with binary coded decimal (BCD) values.

str = ['AB'; 'CD'; 'EF'; 'FA'];

fileID = fopen('bcd.bin','w');
fwrite(fileID,hex2dec(str),'ubit8');
fclose(fileID);

Read 1 byte at a time.

fileID = fopen('bcd.bin');
onebyte = fread(fileID,4,'*ubit8');

Display the BCD values.

disp(dec2hex(onebyte))

AB
CD
EF
FA

Return to the beginning of the file using frewind. If you read 4 bits at a time on a little-endian system, your results appear in the wrong order.

frewind(fileID)

err = fread(fileID,8,'*ubit4');
disp(dec2hex(err))

B
A
D
C
F
E
A
F

Return to the beginning of the file using frewind. Read the data 4 bits at a time as before, but specify a big-endian ordering to display the correct results.

frewind(fileID)

correct = fread(fileID,8,'*ubit4','ieee-be');
disp(dec2hex(correct))

A
B
C
D
E
F
F
A

Close the file.

fclose(fileID);

Input Arguments

fileID — File identifier

integer

File identifier of an open binary file, specified as an integer. Before reading a file with fread, you must use fopen to open the file and obtain its identifier fileID.

Data Types: double

sizeA — Dimensions of output array

Inf (default) | integer | two-element row vector

Dimensions of the output array, A, specified as Inf, an integer, or a two-element row vector.

Form of the sizeA Input	Dimensions of the output array, A
Inf	Column vector, with each element containing a value in the file.
n	Column vector with n elements.
[m,n]	m-by-n matrix, filled in column order. n can be Inf, but m cannot.

precision — Class and size of values to read

'uint8=>double' (default) | character vector or string scalar

Class and size in bits of the values to read, specified as a character vector or a string scalar in one of the following forms. Optionally the input specifies the class of the output matrix, A.

Form of the precision Input	Description
source	Input values are of the class specified by source. Output matrix A is class double. Example: 'int16'
source=>output	Input values are of the class specified by source. The class of the output matrix, A, is specified by output. Example: 'int8=>char'
*source	The input values and the output matrix, A, are of the class specified by source. For bitn or ubitn precisions, the output has the smallest class that can contain the input. Example: '*ubit18' This is equivalent to 'ubit18=>uint32'
N*source or N*source=>output	Read N values before skipping the number of bytes specified by the skip argument. Example: '4*int8'

The following table shows possible values for source and output.

Value Type	Precision	Bits (Bytes)
Integers, unsigned	'uint'	32 (4)
	'uint8'	8 (1)
	'uint16'	16 (2)
	'uint32'	32 (4)
	'uint64'	64 (8)
	'uchar'	8 (1)
	'unsigned char'	8 (1)
	'ushort'	16 (2)
	'ulong'	32 (4)
	'ubitn'	1 ≤ n ≤ 64
Integers, signed	'int'	32 (4)
	'int8'	8 (1)
	'int16'	16 (2)
	'int32'	32 (4)
	'int64'	64 (8)
	'integer*1'	8 (1)
	'integer*2'	16 (2)
	'integer*4'	32 (4)
	'integer*8'	64 (8)
	'schar'	8 (1)
	'signed char'	8 (1)
	'short'	16 (2)
	'long'	32 (4)
	'bitn'	1 ≤ n ≤ 64
Floating-point numbers	'single'	32 (4)
	'double'	64 (8)
	'float'	32 (4)
	'float32'	32 (4)
	'float64'	64 (8)
	'real*4'	32 (4)
	'real*8'	64 (8)
Characters	'char*1'	8 (1)
	'char'	The MATLAB®char type is not a fixed size, and the number of bytes depends on the encoding scheme associated with the file. Set encoding with fopen.

For most values of source, if fread reaches the end of the file before reading a complete value, it does not return a result for the final value. However, if source is bitn or ubitn, then fread returns a partial result for the final value.

Note

To preserve NaN and Inf values in MATLAB, read and write data of class double or single.

Data Types: char | string

skip — Number of bytes to skip

0 (default) | scalar

Number of bytes to skip after reading each value, specified as a scalar. If you specify a precision of bitn or ubitn, specify skip in bits.

Use the skip argument to read data from noncontiguous fields in fixed-length records.

machinefmt — Order for reading bytes

'n' (default) | 'b' | 'l' | 's' | 'a' | ...

Order for reading bytes in the file, specified as a character vector or a string scalar. Specify machinefmt as one of the values in the table that follows. For bitn and ubitn precisions, machinefmt specifies the order for reading bits within a byte, but the order for reading bytes remains your system byte ordering.

'n' or 'native'	Your system byte ordering (default)
'b' or 'ieee-be'	Big-endian ordering
'l' or 'ieee-le'	Little-endian ordering
's' or 'ieee-be.l64'	Big-endian ordering, 64-bit long data type
'a' or 'ieee-le.l64'	Little-endian ordering, 64-bit long data type

By default, all currently supported platforms use little-endian ordering for new files. Existing binary files can use either big-endian or little-endian ordering.

Data Types: char | string

Output Arguments

A — File data

column vector | matrix

File data, returned as a column vector. If you specified the sizeA argument, then A is a matrix of the specified size. Data in A is class double unless you specify a different class in the precision argument.

count — Number of characters read

scalar

Number of characters read, returned as a scalar value.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The input argument precision must be a constant.

• The source and output classes that precision specifies cannot have these values: 'long', 'ulong', 'unsigned long', 'bitn', or 'ubitn'.

• You cannot use the machinefmt input.

• If the source or output that precision specifies is a C type, for example, int, then the target and production sizes for that type must:

  • Match.

  • Map directly to a MATLAB type.

• The source type that precision specifies must map directly to a C type on the target hardware.

• If the fread call reads the entire file, then all of the data must fit in the largest array available for code generation.

• If sizeA is not constant or contains a nonfinite element, then dynamic memory allocation is required.

• The code generator for the fread function treats the char value for source or output as a signed 8-bit integer. Use values between 0 and 127 only.

• The generated code does not report file read errors. Therefore, you must write your own file read error handling in your MATLAB code. In your error handling code, consider checking that the number of bytes read matches the number of bytes that you requested. For example:

  ...
  N = 100;
  [vals, numRead] = fread(fid, N, '*double');
  if numRead ~= N
      % fewer elements read than expected
  end
  ...

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a

R2024b: Read data over HTTP and HTTPS using low-level file functions

You can read data from primary online sources by performing low-level file read operations over an internet URL.

R2022b: Use function in thread-based environments

This function supports thread-based environments.