Documentation Center

  • Trials
  • Product Updates

fread

Read data from binary file

Syntax

  • A = fread(fileID) example
  • A = fread(fileID,sizeA)
  • A = fread(fileID,sizeA,precision) example
  • A = fread(fileID,sizeA,precision,skip) example
  • A = fread(fileID,sizeA,precision,skip,machinefmt) example
  • [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

expand all

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 =

     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 =

     8     1     6
     3     5     7
     4     9     2

Close the file.

fclose(fileID);

Read Text File

Read the contents of the file, fread.m. Transpose the output array, A so that it is a row vector.

fileID = fopen('fread.m');
A = fread(fileID,'*char')';
fclose(fileID);

fread returns the character array, A.

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 =

     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 =

     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(fid,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

expand all

fileID — File identifierinteger

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

sizeA — Dimensions of output arrayInf (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 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.

precision — Class and size of values to read'uint8=>double' (default) | string

Class and size in bits of the values to read, specified as a string 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

1n64

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

1n64

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

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.

skip — Number of bytes to skip0 (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 one of the strings 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.

Output Arguments

expand all

A — File datacolumn 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 readscalar

Number of characters read, returned as a scalar value.

See Also

| | | | | | |

Was this topic helpful?