fread - Read data from binary file - MATLAB (original) (raw)

Read data from binary file

Syntax

Description

[A](#btp1twt-1-A) = fread([fileID](#btp1twt-1-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).

example

[A](#btp1twt-1-A) = fread([fileID](#btp1twt-1-fileID),[sizeA](#btp1twt-1-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](#btp1twt-1-A) = fread([fileID](#btp1twt-1-fileID),[precision](#btp1twt-1-precision)) interprets values in the file according to the form and size described byprecision.

example

[A](#btp1twt-1-A) = fread([fileID](#btp1twt-1-fileID),[sizeA](#btp1twt-1-sizeA),[precision](#btp1twt-1-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 byprecision.

example

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

example

[A](#btp1twt-1-A) = fread(___,[machinefmt](#btp1twt-1-machinefmt)) additionally specifies the order for reading bytes or bits in the file.

example

[[A](#btp1twt-1-A),[count](#btp1twt-1-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

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.

Name Size Bytes Class Attributes

A 9x1 72 double

Close the file.

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.

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')

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

Return to the beginning of the file.

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)

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

Close the file.

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.

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))

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))

Close the file.

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 its identifier fileID.

Data Types: double

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

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.

The following table shows possible values for_source_ and_output_.

For most values of source, iffread reaches the end of the file before reading a complete value, it does not return a result for the final value. However, if_source_ isbit_`n`_ orubit_`n`_, thenfread returns a partial result for the final value.

Note

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

Data Types: char | string

Number of bytes to skip after reading each value, specified as a scalar. If you specify a precision ofbit_`n`_ orubit_`n`_, specifyskip 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. Forbit_`n`_ andubit_`n`_ precisions,machinefmt specifies the order for reading bits within a byte, but the order for reading bytes remains your system byte ordering.

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 thesizeA argument, then A is a matrix of the specified size. Data in A is classdouble unless you specify a different class in theprecision argument.

Number of characters read, returned as a scalar value.

Extended Capabilities

expand all

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','bit_`n`_', or'ubit_`n`_'.
• You cannot use the machinefmt input.
• If the source or output thatprecision 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 oroutput as a signed 8-bit integer. Use values between 0 and127 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
  ...

Version History

Introduced before R2006a

expand all

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

This function supports thread-based environments.