Import Binary Data with Low-Level I/O

Low-Level Functions for Importing Data
Low-level file I/O functions allow the most direct control over reading or writing data to a file. However, these functions require that you specify more detailed information about your file than the easier-to-use
high-level functions. For a complete list of high-level functions and the file formats they support, see

Supported File Formats for Import and Export.

If the high-level functions cannot import your data, use one of the following:

fscanf

, which reads formatted data in a text or ASCII file; that is, a file you can view in a text editor. For more information, see

Reading Data in a Formatted Pattern.

fgetl

and

fgets

, which read one line of a file at a time, where a newline character separates each line. For more information, see

Reading Data Line-by-Line.

fread

, which reads a stream of data at the byte or bit level. For more information, see

Reading Binary Data in a File.

Note:   The low-level file I/O functions are based on functions in the ANSI® Standard C Library. However, MATLAB® includes
vectorized versions of the functions, to read and write data in an array with minimal control loops.

Reading Binary Data in a File
As with any of the low-level I/O functions, before importing, open the file with

fopen

, and obtain a file identifier. When you finish processing a file, close it with

fclose

(
fileID
)

.

By default,

fread

reads a file 1 byte at a time, and interprets each byte as an 8-bit unsigned integer (

uint8

).

fread

creates a column vector, with one element for each byte in the file. The values in the column vector are of class

double

.

For example, consider the file

nine.bin

, created as follows:

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

To read all data in the file into a 9-by-1 column vector of class

double

:

fid = fopen('nine.bin');
col9 = fread(fid);
fclose(fid);

Changing the Dimensions of the Array
By default,

fread

reads all values in the file into a column vector. However, you can specify the number of values to read, or describe a two-dimensional output matrix.

For example, to read

nine.bin

, described in the previous example:

fid = fopen('nine.bin');

% Read only the first six values
col6 = fread(fid, 6);

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

% Read first four values into a 2-by-2 matrix
frewind(fid);
two_dim4 = fread(fid, [2, 2]);

% Read into a matrix with 3 rows and
% unspecified number of columns
frewind(fid);
two_dim9 = fread(fid, [3, inf]);

% Close the file
fclose(fid);

Describing the Input Values

If the values in your file are not 8-bit unsigned integers, specify the size of the values.

For example, consider the file

fpoint.bin

, created with double-precision values as follows:

myvals = [pi, 42, 1/3];

fid = fopen('fpoint.bin','w');
fwrite(fid, myvals, 'double');
fclose(fid);

To read the file:

fid = fopen('fpoint.bin');

% read, and transpose so samevals = myvals
samevals = fread(fid, 'double')';

fclose(fid);

For a complete list of precision descriptions, see the

fread

function reference page.

Saving Memory
By default,

fread

creates an array of class

double

. Storing double-precision values in an array requires more memory than storing characters, integers, or single-precision values.

To reduce the amount of memory required to store your data, specify the class of the array using one of the following methods:

Match the class of the input values with an asterisk (

'*'

). For example, to read single-precision values into an array of class

single

, use the command:

mydata = fread(fid,'*single')

Map the input values to a new class with the

'=>'

symbol. For example, to read

uint8

values into an

uint16

array, use the command:

mydata = fread(fid,'uint8=>uint16')

For a complete list of precision descriptions, see the

fread

function reference page.

Reading Portions of a File

MATLAB low-level functions include several options for reading portions of binary data in a file:

Read a specified number of values at a time, as described in
Changing the Dimensions of the Array. Consider combining this method with
Testing for End of File.

Move to a specific location in a file to begin reading. For more information, see

Moving within a File.

Skip a certain number of bytes or bits after each element read. For an example, see

Write and Read Complex Numbers.

Testing for End of File
When you open a file, MATLAB creates a pointer to indicate the current position within the file.

Note:   Opening an empty file does not move the file position indicator to the end of the file. Read operations, and the

fseek

and

frewind

functions, move the file position indicator.

Use the

feof

function to check whether you have reached the end of a file.

feof

returns a value of

1

when the file pointer is at the end of the file. Otherwise, it returns

0

.

For example, read a large file in parts:

filename = 'largedata.dat';		% hypothetical file
segsize = 10000;

fid = fopen(filename);

while ~feof(fid)
currData = fread(fid, segsize);
if ~isempty(currData)
disp('Current Data:');
disp(currData);
end
end

fclose(fid);

Moving within a File
To read or write selected portions of data, move the file position indicator to any location in the file. For example, call

fseek

with the syntax

fseek(fid,offset,origin);

where:

fid

is the file identifier obtained from

fopen

.

offset

is a positive or negative offset value, specified in bytes.

origin

specifies the location from which to calculate the position:

'bof'

Beginning of file

'cof'

Current position in file

'eof'

End of file

Alternatively, to move easily to the beginning of a file:

frewind(fid);

Use

ftell

to find the current position within a given file.

ftell

returns the number of bytes from the beginning of the file.

For example, create a file

five.bin

:

A = 1:5;
fid = fopen('five.bin','w');
fwrite(fid, A,'short');
fclose(fid);

Because the call to

fwrite

specifies the

short

format, each element of

A

uses two storage bytes in

five.bin

.

Reopen

five.bin

for reading:

fid = fopen('five.bin','r');

Move the file position indicator forward 6 bytes from the beginning of the file:

status = fseek(fid,6,'bof');

Read the next element:

four = fread(fid,1,'short');

The act of reading advances the file position indicator. To determine the current file position indicator, call

ftell:

position = ftell(fid)

position =
8

To move the file position indicator back 4 bytes, call

fseek

again:

status = fseek(fid,-4,'cof');

Read the next value:

three = fread(fid,1,'short');

Reading Files Created on Other Systems
Different operating systems store information differently at the byte or bit level:

Big-endian systems store bytes starting with the largest address in memory (that is, they start with the big end).

Little-endian systems store bytes starting with the smallest address (the little end).

Windows® systems use little-endian byte ordering, and UNIX® systems use big-endian byte ordering.

To read a file created on an opposite-endian system, specify the byte ordering used to create the file. You can specify the ordering in the call to open the file, or in the call to read the file.

For example, consider a file with double-precision values named

little.bin

, created on a little-endian system. To read this file on a big-endian system, use one (or both) of the following commands:

Open the file with

fid = fopen('little.bin', 'r', 'l')

Read the file with

mydata = fread(fid, 'double', 'l')

where

'l'

indicates little-endian ordering.

If you are not sure which byte ordering your system uses, call the

computer

function:

[cinfo, maxsize, ordering] = computer

The returned

ordering

is

'L'

for little-endian systems, or

'B'

for big-endian systems.

Opening Files with Different Character Encodings
Encoding schemes support the characters required for particular alphabets, such as those for Japanese or European languages. Common encoding schemes include US-ASCII or UTF-8.

The encoding scheme determines the number of bytes required to read or write

char

values. For example, US-ASCII characters always use 1 byte, but UTF-8 characters use up to 4 bytes. MATLAB automatically processes the required number of bytes for each

char

value based on the specified encoding scheme. However, if you
specify a

uchar

precision, MATLAB processes each byte as

uint8

, regardless of the specified encoding.

If you do not specify an encoding scheme,

fopen

opens files for processing using the default encoding for your system. To determine the default, open a file, and call

fopen

again with the syntax:

[filename, permission, machineformat, encoding] = fopen(fid);

If you specify an encoding scheme when you open a file, the following functions apply that scheme:

fscanf

,

fprintf

,

fgetl

,

fgets

,

fread

, and

fwrite

.

For a complete list of supported encoding schemes, and the syntax for specifying the encoding, see the

fopen

reference page.