Export Binary Data with Low-Level I/O

Low-Level Functions for Exporting 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 export your data, use one of the following:

fprintf

, which writes formatted data to a text or ASCII file; that is, a file you can view in a text editor or import into a spreadsheet. For more information, see

Export to Text Data Files with Low-Level I/O.

fwrite

, which writes a stream of binary data to a file. For more information, see

Write Binary Data to 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.

Write Binary Data to a File
Open Script

This example shows how to use the

fwrite

function to export a stream of binary data to a file.

Create a file named

nine.bin

with the integers from 1 to 9. As with any of the low-level I/O functions, before writing, open or create a file with

fopen

and obtain a file identifier.

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

By default,

fwrite

writes values from an array in column order as 8-bit unsigned integers (

uint8

).

When you finish processing a file, close it with

fclose

.

fclose(fileID);

Create a file with double-precision values. You must specify the precision of the values if the values in your matrix are not 8-bit unsigned integers.

mydata = [pi 42 1/3];

fileID = fopen('double.bin','w');
fwrite(fileID,mydata,'double');
fclose(fileID);

Overwrite or Append to an Existing Binary File
Open Script

This example shows how to overwrite a portion of an existing binary file and append values to the file.

By default,

fopen

opens files with read access. To change the type of file access, use the permission specifier in the call to

fopen

. Possible permission specifiers include:

'r'

for reading

'w'

for writing, discarding any existing contents of the file

'a'

for appending to the end of an existing file

To open a file for both reading and writing or appending, attach a plus sign to the permission, such as

'w+'

or

'a+'

. If you open a file for both reading and writing, you must call

fseek

or

frewind

between read and write operations.

Overwrite a Portion of an Existing File

Create a file named

magic4.bin

, specifying permission to write and read.

fileID = fopen('magic4.bin','w+');
fwrite(fileID,magic(4));

The original magic(4) matrix is:

16     2     3    13
5    11    10     8
9     7     6    12
4    14    15     1

The file contains 16 bytes, 1 for each value in the matrix.

Replace the values in the second column of the matrix with the vector,

[44 44 44 44]

. To do this, first seek to the fourth byte from the beginning of the file using

fseek

.

fseek(fileID,4,'bof');

Write the vector

[44 44 44 44]

using

fwrite

.

fwrite(fileID,[44 44 44 44]);

Read the results from the file into a 4-by-4 matrix.

frewind(fileID);
newdata = fread(fileID,[4,4])

newdata =

16    44     3    13
5    44    10     8
9    44     6    12
4    44    15     1

Close the file.

fclose(fileID);

Append Binary Data to Existing File

Append the values

[55 55 55 55]

to

magic4.bin

. First. open the file with permission to append and read.

fileID = fopen('magic4.bin','a+');

Write values at end of file.

fwrite(fileID,[55 55 55 55]);

Read the results from the file into a 4-by-5 matrix.

frewind(fileID);
appended = fread(fileID, [4,5])

appended =

16    44     3    13    55
5    44    10     8    55
9    44     6    12    55
4    44    15     1    55

Close the file.

fclose(fileID);

Create a File for Use on a Different System
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 create a file for use on an opposite-endian system, specify the byte ordering for the target system. You can specify the ordering in the call to open the file, or in the call to write the file.

For example, to create a file named

myfile.bin

on a big-endian system for use on a little-endian system, use one (or both) of the following commands:

Open the file with

fid = fopen('myfile.bin', 'w', 'l')

Write the file with

fwrite(fid, mydata, precision, '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.

Open 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.

Write and Read Complex Numbers
Open Script

This example shows how to write and read complex numbers in binary files.

The available precision values for

fwrite

do not explicitly support complex numbers. To store complex numbers in a file, separate the real and imaginary components and write them separately to the file. There are two ways to do this:

Write all real components followed by all imaginary components

Interleave the components

Use the approach that allows you to read the data in your target application.

Separate Real and Imaginary Components

Create an array that contains complex values.

nrows = 5;
ncols = 5;
z = complex(rand(nrows, ncols), rand(nrows, ncols))

z =

Columns 1 through 4

0.8147 + 0.7577i   0.0975 + 0.7060i   0.1576 + 0.8235i   0.1419 + 0.4387i
0.9058 + 0.7431i   0.2785 + 0.0318i   0.9706 + 0.6948i   0.4218 + 0.3816i
0.1270 + 0.3922i   0.5469 + 0.2769i   0.9572 + 0.3171i   0.9157 + 0.7655i
0.9134 + 0.6555i   0.9575 + 0.0462i   0.4854 + 0.9502i   0.7922 + 0.7952i
0.6324 + 0.1712i   0.9649 + 0.0971i   0.8003 + 0.0344i   0.9595 + 0.1869i

Column 5

0.6557 + 0.4898i
0.0357 + 0.4456i
0.8491 + 0.6463i
0.9340 + 0.7094i
0.6787 + 0.7547i

Separate the complex values into real and imaginary components.

z_real = real(z);
z_imag = imag(z);

Write All Real Components Follwed By Imaginary Components

Write all the real components,

z_real

, followed by all the imaginary components,

z_imag

, to a file named

complex_adj.bin

.

adjacent = [z_real z_imag];

fileID = fopen('complex_adj.bin', 'w');
fwrite(fileID,adjacent,'double');
fclose(fileID);

Read the values from the file using

fread

.

fileID = fopen('complex_adj.bin');
same_real = fread(fileID, [nrows, ncols], 'double');
same_imag = fread(fileID, [nrows, ncols], 'double');
fclose(fileID);

same_z = complex(same_real, same_imag);

Interleave Real and Imaginary Components

An alternative approach is to interleave the real and imaginary components for each value.

fwrite

writes values in column order, so build an ar
9d61
ray that combines the real and imaginary parts by alternating rows.

First, preallocate the interleaved array.

interleaved = zeros(nrows*2, ncols);

Alternate real and imaginary data.

newrow = 1;
for row = 1:nrows
interleaved(newrow,:) = z_real(row,:);
interleaved(newrow + 1,:) = z_imag(row,:);
newrow = newrow + 2;
end

Write the interleaved values to a file named

complex_int.bin

.

fileID = fopen('complex_int.bin','w');
fwrite(fileID, interleaved, 'double');
fclose(fileID);

Open the file for reading and read the real values from the file. The fourth input to

fread

tells the function to skip the specified number of bytes after reading each value.

fileID = fopen('complex_int.bin');
same_real = fread(fileID, [nrows, ncols], 'double', 8);

Return to the first imaginary value in the file. Then, read all the imaginary data.

fseek(fileID, 8, 'bof');
same_imag = fread(fileID, [nrows, ncols], 'double', 8);
fclose(fileID);

same_z = complex(same_real, same_imag);