Learn more about MATLAB

fread - Read data from binary file

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, machineformat) [A, count] = fread(...)

Description

A = fread(fileID) reads data from a binary file into column vector A and positions the file pointer at the end-of-file marker.

A = fread(fileID, sizeA) reads sizeA elements into A and positions the file pointer after the last element read. sizeA can be an integer, or can have the form [m,n].

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

A = fread(fileID, sizeA, precision, skip) skips skip bytes after reading each value. If precision is bitn or ubitn, specify skip in bits. The sizeA parameter is optional.

A = fread(fileID, sizeA, precision, skip, machineformat) reads data with the specified machineformat. The sizeA and skip parameters are optional.

[A, count] = fread(...) returns the number of elements fread reads into A.

Inputs

fileID

An integer file identifier obtained from fopen.

sizeA

Dimensions of the output array A. Specify in one of the following forms:

`inf`	Column vector with the number of elements in the file. (default)
`n`	Column vector with `n` elements. If the file has fewer than `n` elements, `fread` pads `A` with zeros.
`[m,n]`	`m`-by-`n` matrix, filled in column order. If the file has fewer than `m`*`n` elements, `fread` pads `A` with zeros. `n` can be `inf`, but `m` cannot.

precision

String that specifies the form and size of the values to read. Optionally includes the class for the output matrix A.

Use one of the following forms:

`'source'`	Specifies class of input values. Output matrix `A` is class `double`. Example: `'int16'`
`'source=>output'`	Specifies classes of input and output. Example: `'int8=>char'`
`'*source'`	Output has the same class as input. Example: `'uint8'` For `'bitn'` or `'ubitn'` precisions, output has the smallest class that can contain the input. Example: `'ubit18'` is equivalent to `'ubit18=>uint32`'
`'Nsource'` OR `'Nsource=>output'`	Valid if you specify a `skip` parameter. Read `N` values before each skip. Example: `'4*int8'`

The following table shows possible values for source and output.

Value Type Precision Bits (Bytes)

Integers, unsigned
uint
uint8
uint16
uint32
uint64
uchar
unsigned char
ushort
ulong
ubitn
32 (4)
8 (1)
16 (2)
32 (4)
64 (8)
8 (1)
8 (1)
16 (2)
system-dependent
1 ≤ n ≤ 64

Integers, signed
int
int8
int16
int32
int64
integer*1
integer*2
integer*3
integer*4
schar
signed char
short
long
bitn
32 (4)
8 (1)
16 (2)
32 (4)
64 (8)
8 (1)
16 (2)
32 (4)
64 (8)
8 (1)
8 (1)
16 (2)
system-dependent
1 ≤ n ≤ 64

Floating-point numbers
single
double
float
float32
float64
real*4
real*8
32 (4)
64 (8)
32 (4)
32 (4)
64 (8)
32 (4)
64 (8)

Characters
char*1
char
8 (1)
Depends on the encoding scheme associated with the file. Set encoding with fopen.

long and ulong are 32 bits on 32-bit systems, and 64 bits on 64-bit systems.

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

Default: 'uint8=>double'

skip

Number of bytes to skip after reading each value. If you specify a precision of bitn or ubitn, specify skip in bits. Use this parameter to read data from noncontiguous fields in fixed-length records.

Default: 0

machineformat

String that specifies the order for reading bytes within the file. For bitn and ubitn precisions, specifies the order for reading bits within a byte. Specify machineformat to read and write to the file on different systems, or to read parts of a byte in a specific order.

Possible values are:

`'n'` or `'native'`	The byte ordering that your system uses (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 data type
`'a'` or `'ieee-le.l64'`	Little-endian ordering, 64-bit data type

Windows systems use little-endian ordering, and most UNIX systems use big-endian ordering, for both bytes and bits. Solaris systems use big-endian ordering for bytes, but little-endian ordering for bits.

Outputs

`A`	A column vector, unless you specify `sizeA` with the form `[m,n]`. Data in `A` is class `double` unless you specify a different class in the `precision` argument.
`count`	The number of elements that `fread` successfully reads.

Examples

Read the contents of a file:

% Create the file
fid = fopen('magic5.bin', 'w');
fwrite(fid, magic(5));
fclose(fid);

% Read the contents back into an array
fid = fopen('magic5.bin');
m5 = fread(fid, [5, 5], '*uint8');
fclose(fid);

Simulate the type function with fread, to display the contents of a text file:

fid = fopen('fread.m');

% read the entire file as characters
% transpose so that F is a row vector
F = fread(fid, '*char')'

fclose(fid);

If you do not specify the precision, fread applies the default uint8=>double:

fid = fopen('fread.m');
F_nums = fread(fid, 6)'		% read the first 6 bytes ('%FREAD')
fclose(fid);

This code returns

F_nums = 
    37    70    82    69    65    68

Read selected rows or columns from a file:

% Create a file with values from 1 to 9
fid = fopen('nine.bin', 'w');
alldata = reshape([1:9],3,3);
fwrite(fid, alldata);
fclose(fid);

% Read the first six values into two columns
fid = fopen('nine.bin');
two_cols = fread(fid, [3, 2]);

% Return to the beginning of the file
frewind(fid);

% Read two values at a time, skip one
% Returns six values into two rows
% (first two rows of 'alldata')

two_rows = fread(fid, [2, 3], '2*uint8', 1);

% Close the file
fclose(fid);

Specify machineformat to read separate digits of binary coded decimal (BCD) values correctly:

% Create a file with BCD values
str = ['AB'; 'CD'; 'EF'; 'FA'];

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

% If you read one byte at a time, 
% no need to specify machine format
fid = fopen('bcd.bin');

onebyte = fread(fid, 4, '*ubit8');
disp('Correct data, read with ubit8:')
disp(dec2hex(onebyte))

% However, if you read 4 bits on a little-endian
% system, your results appear in the wrong order
frewind(fid);     % return to beginning of file

part_err = fread(fid, 8, '*ubit4');
disp('Incorrect data on little-endian systems, ubit4:')
disp(dec2hex(part_err))

% Specify a big-endian format for correct results
frewind(fid);

part_corr = fread(fid, 8, '*ubit4', 'ieee-be');
disp('Correct result, ubit4:')
disp(dec2hex(part_corr))

fclose(fid);