Store 
Product Support
1602 - File I/O Guide
- Introduction to File I/O in MATLAB
- High Level Routines
- LOAD/SAVE
- UIGETFILE/UIPUTFILE
- UIIMPORT/IMPORTDATA
- TEXTREAD/STRREAD
- DLMREAD/DLMWRITE/CSVREAD
- WK1READ/WK1WRITE
- XLSREAD
- Relevant Technical Support Solutions
- Low Level Common Routines
- Low Level ASCII Routines
- Low Level Binary Routines
Section 1: Introduction to File I/O in MATLAB
There are a number of file formats that can be read into MATLAB. You should review the list of file formats that are easily read into MATLAB, as well as the functions used to read them. All of the file I/O routines are in MATLAB, so they require no special toolboxes. This Technical Support Guide deals primarily with ASCII, binary, and MAT files. For a complete list of functions available in MATLAB to read and write ASCII, binary, MAT (MATLAB matrix file format), HDF (NCSA's Hierarchical Data Format), image, video, and audio data, type the following at the MATLAB Command Prompt:
help iofun
There are two basic types of file I/O routines in MATLAB: high level and low level. High level routines include ready-made functions which read and write data in specific formats and require very little programming on your part. Low level routines perform more specific tasks and require extra programming on your part, but they are much more flexible.
-
Supported File Types
You can view which text, movie, image, audio, and spreadsheet file types are supported in your version of MATLAB by typing the following at your command line:
help fileformats
Alternately, review the documentation.
You can learn more about any particular function by typing the following at your command line:
help function_name
or
doc function_name
(where function_name is the name of the function in question)
You can also view the File I/O documentation which is available under the Importing and Exporting Data section of the MATLAB Programming documentation.
Note: The MathWorks Technical Support department does not have the resources to develop custom code for each specialized application. Contact our Consulting Group if you would like help in developing your custom code. If, however, a function is not behaving as you think it should, contact Technical Support.
Section 2: High Level Routines
High level routines include ready-made functions that read and write data in specific formats and require very little programming on your part. For example, if you have a text file that you want to import into MATLAB that contains both numbers and letters, you can write a function that uses several calls to low level routines or you can simply use the TEXTREAD function. The key to using high level routines is that the files of interest must be homogeneous. In other words, the files must have a consistent format all the way through. The paragraphs below describe several high level file I/O routines available in MATLAB and also give examples to help illustrate concepts.
-
LOAD/SAVE
Our major high level file I/O routines are the LOAD and SAVE functions. LOAD can read MAT-file data or homogeneous white space delimited ASCII data. SAVE can write MATLAB variables in MAT-file format or (when possible) as white space delimited ASCII data. In most cases, the syntax is quite simple. Download the numeric, space delimited, ASCII file sample_file.txt and follow the example below:
Example: Using LOAD and SAVE to read and write data
% Load the file to the
% matrix, M :
M = load('sample_file.txt')
% Add 5 to M :
M = M +5
% Save M to a .mat
% file called
%'sample_file_plus5.mat':
save sample_file_plus5 M
% Save M to
% an ASCII .txt file
% called 'sample_file_plus5.txt' :
save sample_file_plus5.txt M -ascii
UIGETFILE is a GUI-based interface that is used to prompt you for a file. UIPUTFILE lets you select a file for writing (similar to the Windows 'Save As...' option). Both functions display a dialog box that lists the files and directories in the current directory. With UIGETFILE, you can choose one file of interest. With UIPUTFILE, you can either choose an existing file to rewrite or type in the name of a new file. Both the name and path of the file of interest are returned by both functions.
Example: Using UIGETFILE to select a M-file from your current directory
% This command lists all the M-files in the current directory and
% returns the name and path of the selected file
[fname,pname] = uigetfile('*.m','Sample Dialog Box')
Note: UIGETFILE only supports the selection of one file at this time.
UIIMPORT is a powerful and easy-to-use GUI-based high level routine for reading in complex data files. Like any high level routine, however, the files being read must be homogeneous throughout. IMPORTDATA is the functional form of UIIMPORT and therefore does not open a GUI. You can use IMPORTDATA in a function or script where a GUI-based file import mechanism is not ideal. You can download the 'sample_file2.txt' file, which contains row headers and text and numeric data, and follow the example below:
Example: Using IMPORTDATA to read in a file with headers, text, and numeric data
% This reads in the file 'sample_file2.txt' and creates a
% structure D that contains both data and text data.
% Note the IMPORTDATA command specifies a white space
% as the delimiter of the file, but IMPORTDATA can usually
% detect this on its own
D = importdata('sample_file2.txt','')
To see the actual values in the structure D, you need to dereference the data and text fields. For example, to see the actual values type the following:
data = D.data text = D.textdata
You can also use UIIMPORT to read in the same file and you will get the same structure.
Note: For ASCII data, you must verify that the Import Wizard correctly identified the column delimiter.
TEXTREAD is a powerful and dynamic high level routine designed to read in ASCII formatted text and/or numeric data files. STRREAD is similar to TEXTREAD with the exception that it reads from a string and not a file. Both functions can accept many parameters that enable you to modify exactly the way they work. They return the data read into the output that you specify. These functions effectively give you the "best of both worlds" because they let you read in mixed ASCII and numeric data with one command like high level routines do and you can modify it to fit your particular application like low level routines allow. You can use the 'sample_file2.txt' file for the examples below:
Example 1: Using TEXTREAD to read in an entire file into a cell array
% This command reads in the file fft.m into the cell array, file
file = textread('fft.m','%s','delimiter','\n','whitespace','');
Example 2: Using STRREAD to read the words in a line
% This command uses the cell array created in Example 1 to
% read in each word of line 28 in 'file' to a cell array, words
words = strread(file{28},'%s','delimiter','')
Example 3: Using TEXTREAD to read in text and numeric data from a file with headers
% This command skips the 2 header lines at the top of the file
% and reads in each column to the 4 specified outputs
[c1 c2 c3 c4] = textread('sample_file2.txt','%s %s %s %s','headerlines',2)
Example 4: Using TEXTREAD to read in specific rows of text and numeric data from a file
% This command reads in rows B and C of the file. The 'headerlines'
% property is used to move down to the desired starting row and the
% read operation is performed 2 times
[c1 c2 c3 c4] = textread('sample_file2.txt',...
'%s %s %s %s',2,'headerlines',4)
Example 5: Using TEXTREAD to read in only the numeric data from a file containing text and numbers
% This command reads in only the numeric data in the file. The
% 'headerlines' property is used to move down to the first row
% of interest and the first column of text is ignored with the
% '*' operator
[c2 c3 c4] = textread('sample_file2.txt','%*s %d %d %f','headerlines',3)
The DLMREAD and DLMWRITE functions enable you to read and write delimited ASCII data without using our low level routines. These functions are much easier to use than the low level routines, and what would take a number of lines of code with low level routines can be simplified to one line with DLMREAD and DLMWRITE. CSVREAD reads in comma delimited files; it is a special case of DLMREAD in which the delimiter is taken to be a comma. DLMREAD becomes especially helpful when trying to read in spreadsheet files, which can be saved as space or tab delimited. You can use the 'sample_file.txt' file for the examples below:
Example 1: Using DLMREAD to read in a file with headers, text, and numeric data
% This reads in the file 'sample_file2.txt' and creates a matrix, D,
% with the numeric data this command specifies a white space as the
% delimiter of the file
D = dlmread('sample_file.txt','')
Example 2: Using DLMREAD to extract the first 3 columns of the last 3 rows
% This reads in the first 3 columns of the last 3 rows of
% the data file 'sample_file.txt'into the matrix, D_partial.
D_partial = dlmread('sample_file.txt','',[2 0 4 2])
Example 3: Using DLMWRITE to write a comma delimited file
% This creates a file called 'partialD.txt' that consists of
% the first 3 columns of the last 3 rows of data where each
% element is separated by a comma
dlmwrite('partialD.txt',D_partial,',')
Note: Make sure to note that the indexing for specifying the range of DLMREAD and DLMWRITE starts at 0 not at 1.
WK1READ is used to read in numeric data from a Lotus123 spreadsheet file and WK1WRITE is used to write a matrix to a Lotus123 spreadsheet file.
XLSREAD is used to read in numeric and text data from a Microsoft Excel worksheet.
The following solutions provide additional information on these High Level Routines:
How do I make the names in my file header the names of the variables
I load?
How can I read in a data file that has a header and is ASCII
delimited?
Are there any examples that demonstrate how to read a comma delimited
ASCII file that contains missing data?
How do I use the functional form of the LOAD and SAVE commands?
How do I export a cell array containing double arrays into an ASCII-file format?
Why does MATLAB crash when I try to import binary files using
the Import Wizard?
Section 3: Low Level Common Routines
Low level routines let you fit your file I/O application to your particular task. The low level file I/O routines in MATLAB are based on the same routines as C. They will require more programming on your part, but are very versatile and modular. You can also use low level routines to read and write both ASCII and binary files. The routines in the section below are common between both file formats and can be used when dealing with either ASCII or binary data.
-
FOPEN/FCLOSE
FOPEN opens a file for either reading or writing and returns an integer file identifier or fid. FCLOSE is used to close the open file so that it can be used by other applications. Several parameters can be passed to FOPEN to address factors, such as identifying machine format, determining if the file addressed will be read or written to, or checking if the file addressed is treated as ASCII or binary, and more. See the function documentation for a complete list of available parameters. See the FTELL/FEOF section below for examples.
Note: Under Windows, while the file is open, it cannot be accessed by another function call, or a sharing violation will occur. This is not an issue on UNIX or Linux because the descriptors of different applications are independent.
Also, a file is always opened as a binary file unless a t is included as part of the second argument. This only makes a difference under Windows.
Portability Note: When using FOPEN to access a binary data file, specify the machine format of the data, for example little-endian or big-endian. See the FREAD/FWRITE Note for more information.
These two functions are used to navigate through a file. When a file is opened with FOPEN, an internal pointer is positioned before the first byte in the file. This is where MATLAB will start reading. As other commands are used, the pointer inside the file moves as specified by the commands until the file is closed. FSEEK is a routine that lets you move to a particular point in the file. This routine gives you the flexibility to move byte-by-byte (or element-by-element) to any desired location in the file. FREWIND is a special call to FSEEK that places the file position at the very beginning of the file.
Example: Using FSEEK to perform the FREWIND function
% This function call sets 'position' to the beginning of the
% file ('bof') identified by 'fid'.
position = fseek(fid,0,'bof')
These two functions are used to identify where the internal pointer lies in the file. FTELL returns how many bytes (or elements) into the file the pointer is with respect to the beginning of the file. FEOF is a check that returns 1 if the end-of-file marker is reached. This is a useful check that can be used in a loop when reading data. You can use the 'sample_file.txt' file for the examples below:
Example 1: Opening, Closing, and Navigating a File
% 'sample_file.txt' is
% opened as a read-only
% text file:
fid = fopen('sample_file.txt','rt');
% FTELL is used to show
% we are at the
% beginning of the file:
ftell(fid);
% FSEEK is used to move
% 3 bytes into the file
% relative to the
% beginning of the file:
fseek(fid,3,'bof');
% FTELL is used to show
% that we are 3 bytes
% into the file
% relative to the
% beginning of the file:
ftell(fid)
% FSEEK is used to move
% 5 bytes into the file
% relative to the
% current position in
% the file:
fseek(fid,5,'cof');
% FTELL is used to show
% that we are 8 bytes
% into the file relative
% to the beginning of
% the file:
ftell(fid)
% FSEEK is used to move
% to the end of the file:
fseek(fid,0,'eof');
% FTELL is used to show
% that we are 60 bytes
% into the file
% relative to the
% beginning of the file:
ftell(fid)
% the file is closed:
fclose(fid);
Example 2: Using FEOF to run a loop while reading data
fid = fopen('sample_file.txt','rt');
i = 0;
% FEOF is used as the
% loop control to read
% until the file ends:
while ~feof(fid)
i = i+1;
% FSCANF is used to
% read in data one
% character at a time :
data = fscanf(fid,'%c',1);
if ~isempty(data)
% the data is stored in
% vector 'a' :
a(i) = data;
end
end
fclose(fid);
Section 4: Low Level ASCII Routines
The low level routines for ASCII files in MATLAB are based on the same routines as C. Most of the functions below require that you specify the format for how the data will be read or written.
Note: MATLAB is column major, while C is row major. This means that even though a file is read or written row by row, it is stored and indexed in MATLAB column by column. This issue may raise some concerns with the formatting when reading and writing data to and from MATLAB. This issue is addressed in the examples below.
The FSCANF and FPRINTF routines are used to read and write formatted ASCII data respectively. FSCANF can read in either text or numbers depending on the formatting string that is used. You can specify the amount and type of data that is read by using the optional parameters. FPRINTF is used to write the data in a matrix to a file. The format that is specified determines how the data is written to the file. See the documentation for FPRINTF for a complete list of available formatting parameters. SSCANF is similar to FSCANF with the exception that it reads from a string and not a file. SPRINTF is similar to FPRINTF with the exception that it writes to a string and not a file.
You can read data from certain parts of the file by using FSEEK and/or a loop to place the file pointer in the appropriate position. You can use the 'sample_file.txt' file for the examples below:
Example 1: Reading only the last line of data using FSCANF and FSEEK
NL = 10;
fid = fopen('sample_file.txt','r');
status = fseek(fid,0,'eof');
% The loop below uses FSEEK to start at the end of the
% file and calls FSCANF to read data backwards until a new
% line character is reached.
i = 0;
last_line = '';
while 1
% If the file is only 1 line with no new line marker, break
if fseek(fid,-1,'cof') == -1, break, end
c = fscanf(fid,'%c',1);
% If a new line marker other than the terminating new
% line marker is found, break
if c == char(NL) & i ~= 0 , break, end
i = i + 1;
last_line(1,i) = c;
if fseek(fid,-1,'cof') == -1, break, end
end
% Because the data was read backwards, it is horizontally
% flipped with FLIPLR.
last_line = fliplr(last_line);
fclose(fid);
Example 1a: Using SPRINTF to remove the new line marker from last_line
% This line uses STRREP and SPRINTF to remove the new
% line marker (\n) from the last_line string
last_line = strrep(last_line,sprintf('\n'),'')
We can continue Example 1 and 1a with Examples 2 and 3 to illustrate how we can use the FPRINTF function to write the acquired last_line data to specific locations in the file.
Example 2: Using FPRINTF to write data to the end of the file
% Opening the file to append to the end of it
fid = fopen('sample_file.txt','a');
fprintf(fid,'%s',last_line);
fclose(fid);
Example 3: Using FPRINTF to write data to a specific line in the file
% Opening the file to both read and write
fid = fopen('sample_file.txt','r+');
% Can change 'loc' to insert data at any line in file.
% When loc=2, data willinserted at line 3
loc = 2;
for i = 1:loc
%Used FGETL to move file pointer a whole line at a time:
%See FGETL section below for more information
temp_line = fgetl(fid);
end;
fprintf(fid,'\n');
fseek(fid,-2,'cof');
% This call to FPRINTF utilizes the vectorized feature of the
% MATLAB version: see below for more information
fprintf(fid,'%s',last_line);
fprintf(fid,'\n');
fclose(fid);
Limitation: If you use r+, there is no way to decrease the size of the file. For example, if you try to replace the last line of the file by a shorter line, the characters at the end of line from the old line will still be there. Unless you rewrite the file completely there is nothing you can do about it.
Example 3a: Using FPRINTF to write data to a specific line in the file (more sophisticated)
% This example differs from Example 3 in that it tries to
% squeeze out any extra characters if the new
% line is shorter than the line it is replacing.
% Opening the file to both read and write
fid = fopen('sample_file.txt','r+');
% Can change 'loc' to insert data at any line in file.
% When loc=2, data will inserted at line 3
loc = 2;
for i = 1:loc
% Used FGETL to move file pointer a whole line at a time:
% See FGETL section below for more information
temp_line = fgetl(fid);
if ~ischar(temp_line), break, end
end;
if ischar(temp_line)
p = ftell(fid)
temp_line = fgetl(fid);
if ischar(temp_line)
% Read in the rest of the file after line of interest
% with FREAD
c = fread(fid,inf,'uchar');
% Place the internal pointer back to the line of interest
fseek(fid,p,'bof');
% Print the last_line data to the current position
fprintf(fid,'%s',last_line);
% Write the rest of the data in the file with FWRITE
fwrite(fid,c,'uchar');
else
fprintf(fid,'%s',last_line);
end
else
fprintf('Not enough lines in file to skip. Nothing appended...\n');
end
fclose(fid);
Note: A seek command must be used between any read and write operation when the file is opened in update mode ('r+').
An important difference between the MATLAB FSCANF and FPRINTF functions and their C counterparts is that the MATLAB versions are vectorized for nonscalar arguments. The functions recycle the format string through the elements of A (column wise) until all the elements are used up. We can continue the above examples with Example 4 and 5 below:
Example 4: Difference between FSCANF in MATLAB and C
% In C, the function call below would read in one character
% in MATLAB, the code recycles '%f' and reads in the whole
% file and stores it as a column
fid = fopen('sample_file.txt','r');
a_temp = fscanf(fid,'%f')
Example 5 illustrates how to deal with the fact that MATLAB is column major and C is row major:
Example 5: MATLAB is column major and C is row major
% The RESHAPE command is used to put the data into the % transposed shape as the file and then it is transposed % back with the ' operator % NOTE: the size below assumes you have done Examples 1-3. % If not, then use: a = reshape(a_temp,5,5)' a = reshape(a_temp,5,6)' fclose(fid);
FGETL and FGETS are used to read ASCII formatted data one entire line at a time. Both functions operate in the same manner, with the exception that FGETL returns the line without the line terminator (either \r\n or \n) while FGETS returns the line with the line terminator. You can use the 'sample_file.txt' file for the example below:
Example 1: Displaying the contents of a file using FGETL in a loop
fid = fopen('sample_file.txt');
while 1
tline = fgetl(fid);
if ~ischar(tline), break, end
disp(tline)
end
fclose(fid);
Example 2: Displaying the contents of a file using FGETS in a loop
fid = fopen('sample_file.txt');
while 1
tline = fgets(fid);
if ~ischar(tline), break, end
disp(tline)
end
fclose(fid);
Example 3: Reading only the last line of data using FGETL and FSEEK
NL = 10;
fid = fopen('sample_file.txt','r');
% The loop below uses FSEEK to start at the end of the file and calls
% FSCANF to read data backwards to check for new line markers.
status = fseek(fid,0,'eof');
i = 0;
found = 0;
while 1
% If the file is only 1 line with no new line marker, break
if fseek(fid,-1,'cof') == -1, break, end
c = fscanf(fid,'%c',1);
% If a new line marker other than the terminating new
% line marker is found, break
if c == char(NL) & i ~= 0 , found = 1; break, end
i = i + 1;
if fseek(fid,-1,'cof') == -1, break, end
end
if found | i > 0
% Last line is captured with FGETL
last_line = fgetl(fid)
end
See below for some useful Technical Support solutions:
How can I read in mixed ASCII and numeric data?How do I read an ASCII data file from stand-alone code generated by the MATLAB Compiler?
Why does SSCANF return data that is incorrectly formatted?
Is it possible to use FSCANF or SSCANF to read ASCII data that contains NaNs and Infs?
Why am I unable to use the same format statement for FPRINTF and FSCANF?
Low Level Binary Routines
Like the low level routines for ASCII files, the low level file I/O routines for binary files in MATLAB are based on the same routines as C. The functions below require that you specify the precision for how the data will be read or written.
Note: MATLAB is column major while C is row major. This means that even though a file is read or written row by row, it is stored and indexed in MATLAB column by column. This issue may raise some concerns with the formatting when reading and writing data to and from MATLAB. This issue is addressed in the examples below.
FREAD and FWRITE are the binary counterparts of FSCANF and FPRINTF, respectively. The FREAD and FWRITE routines are used to read and write binary data. The syntax of the binary functions are slightly different than their ASCII counterparts. FREAD and FWRITE require that a precision parameter be passed as opposed to a format string like FPRINTF and FSCANF. The precision specifies the number of bits and the data type that will be either read or written. See the documentation for FREAD for a complete list of available precision parameters. A size parameter must be specified for FREAD so that the number of elements to be read is known (each element is defined by the precision).
Note: When dealing with binary data, it is important to specify the correct machine format (endian) used to encode the data. This parameter is specified with the FOPEN function. See the documentation for FOPEN for a complete list of available machine format parameters. If the data was written under Windows, then it is usually in little endian format. If the data was written on a UNIX system and the default was used, you will need to know the platform it was written on. For example, on Solaris big endian is the default. If you are using MATLAB 6.1 or higher, you can use the COMPUTER command (i.e.: [c,maxsize,endian] = computer;); otherwise see Example 3 below.
Reference the FSCANF/SSCANF/FPRINTF/SPRINTF section above for some examples that can be transposed to use FREAD and FWRITE. You can use the 'sample_file.txt' file for the examples below:
Example 1: Converting an ASCII file to binary
% Opening original ASCII file to read
fid = fopen('sample_file.txt','r');
% Opening binary file to write. Note that the machine format
% for the file is specified as little endian
fid2 = fopen('sample_file.bin','w','l');
% Reading in ASCII data
a = fscanf(fid,'%d');
% Wwriting binary data as a 16 bit signed integer
fwrite(fid2, a, 'int16');
fclose(fid);
fclose(fid2);
Example 2: Little Endian vs. Big Endian
% Opening binary file and specifying the same little endian
% machine format that the file was written in
fid = fopen('sample_file.bin','r','l');
% a1 is a correct representation of the data
a1 = fread(fid,[5 5],'int16')'
fclose(fid);
% opening binary file and specifying a different big endian
% machine format that the file was written in
fid2 = fopen('sample_file.bin','r','b');
% a2 is an incorrect representation of the data
a2 = fread(fid2,[5 5],'int16')'
fclose(fid2);
Example 3: Determining your machine format
% Opening a temporary binary file
% using the default machine format
fid = fopen('temp_file.bin','w');
% using the optional output parameters of FOPEN to learn what is
% the machine format for this open file
[filename permission MACHINE_FORMAT] = fopen(fid);
fclose(fid);
See below for some useful Technical Support solutions:
Can I use FREAD and FWRITE to read and write complex binary files?
