fread

Read data from binary file

collapse all in page

Syntax

A = fread(fileID)
A = fread(fileID,sizeA)
A = fread(fileID,sizeA,precision)
A = fread(fileID,sizeA,precision,skip)
A = fread(fileID,sizeA,precision,skip,machinefmt)
[A,count] = fread(___)

Description

example

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.

example

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

example

A = fread(fileID,sizeA,precision,skip) skips the number of bytes or bits specified by skip after reading each value in the file. The sizeA argument is optional.

example

A = fread(fileID,sizeA,precision,skip,machinefmt) additionally specifies the order for reading bytes or bits in the file. The sizeA and skip arguments are optional.

[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

collapse all

Open Live Script

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);
Open Live Script

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);
Open Live Script

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);
Open Live Script

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

collapse all

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 the fileID.

Data Types: double

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

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

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 InputDescription
sourceInput values are of the class specified by source. Output matrix A is class double.
Example: 'int16'
source=>outputInput values are of the class specified by source. The class of the output matrix, A, is specified by output.
Example: 'int8=>char'
*sourceThe 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 TypePrecisionBits (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

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.

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

collapse all

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.

Number of characters read, returned as a scalar value.

Extended Capabilities

See Also

| | | | | | |

Topics

Introduced before R2006a

MATLAB Documentation

Support