Skip to Main Content Skip to Search
Product Documentation

fopen - Open file, or obtain information about open files

Syntax

fileID = fopen(filename)
fileID = fopen(filename, permission)
fileID = fopen(filename, permission, machineformat)
fileID = fopen(filename, permission, machineformat, encoding)
[fileID, message] = fopen(filename, ...)
fIDs = fopen('all')
[filename, permission, machineformat, encoding] = fopen(fileID)

Description

fileID = fopen(filename) opens the file filename for read access, and returns an integer file identifier.

fileID = fopen(filename, permission) opens the file with the specified permission.

fileID = fopen(filename, permission, machineformat) specifies the order for reading or writing bytes or bits in the file.

fileID = fopen(filename, permission, machineformat, encoding) specifies the character encoding scheme associated with the file.

[fileID, message] = fopen(filename, ...) opens a file. If the operation fails, message is a system-dependent error message. Otherwise, message is an empty string.

fIDs = fopen('all') returns a row vector containing the file identifiers of all open files.

[filename, permission, machineformat, encoding] = fopen(fileID) returns the file name, permission, machine format, and encoding that a previous call to fopen used when it opened the specified file. fopen does not read information from the file to determine these output values. An invalid fileID returns empty strings for all output arguments.

Input Arguments

filename

String in single quotation marks that specifies the name of the file to open. Can include a full or partial path.

On UNIX systems, if filename begins with '~/' or '~username/', the fopen function expands the path to the current or specified user's home directory, respectively.

If you open a file with read access and fopen cannot find filename in the current folder, fopen searches along the MATLAB search path. Otherwise, fopen creates a file in the current directory.

permission

String that describes the type of access for the file: read, write, append, or update. Also specifies whether to open files in binary or text mode.

To open files in binary mode, specify one of the following:

'r'

Open file for reading (default).

'w'

Open or create new file for writing. Discard existing contents, if any.

'a'

Open or create new file for writing. Append data to the end of the file.

'r+'

Open file for reading and writing.

'w+'

Open or create new file for reading and writing. Discard existing contents, if any.

'a+'

Open or create new file for reading and writing. Append data to the end of the file.

'A'

Append without automatic flushing. (Used with tape drives.)

'W'

Write without automatic flushing. (Used with tape drives.)

To read and write to the same file:

  • Open the file in update mode (with a permission that includes a plus sign, '+').

  • Call fseek or frewind between read and write operations. For example, do not call fread followed by fwrite, or fwrite followed by fread, unless you call fseek or frewind between them.

To open files in text mode, attach the letter 't' to the permission, such as 'rt' or 'wt+'. For better performance, do not use text mode. The following applies on Windows systems, in text mode:

  • Read operations that encounter a carriage return followed by a newline character ('\r\n') remove the carriage return from the input.

  • Write operations insert a carriage return before any newline character in the output.

This additional processing is unnecessary for most cases. All MATLAB import functions, and most text editors (including Microsoft Word and WordPad), recognize both '\r\n' and '\n' as newline sequences. However, when you create files for use in Microsoft Notepad, end each line with '\r\n'. For an example, see fprintf.

machineformat

String that specifies the order for reading or writing bytes or bits in the file.

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 long data type

'a' or 'ieee-le.l64'

Little-endian ordering, 64-bit long data type

By default, all currently supported platforms use little-endian ordering for new files. Existing binary files can use either big- or little-endian ordering.

encoding

String that specifies the character encoding scheme to use for subsequent read and write operations, including fscanf, fprintf, fgetl, fgets, fread, and fwrite.

Supported values are:

'Big5'

'ISO-8859-1'

'windows-932'

'EUC-JP'

'ISO-8859-2'

'windows-936'

'GBK'

'ISO-8859-3'

'windows-949'

'Macintosh'

'ISO-8859-4'

'windows-950'

'Shift_JIS'

'ISO-8859-9'

'windows-1250'

'US-ASCII'

'ISO-8859-13'

'windows-1251'

'UTF-8'

'ISO-8859-15'

'windows-1252'

  

'windows-1253'

  

'windows-1254'

  

'windows-1257'

For a list of additional encoding character sets, see http://www.iana.org/assignments/character-sets. If you specify a value for encoding that is not in the list of supported values, MATLAB issues a warning. Specifying other encodings sometimes (but not always) produces correct results.

Default: system-dependent

Output Arguments

fileID

An integer that identifies the file for all subsequent low-level file I/O operations. If fopen cannot open the file, fileID is -1.

MATLAB reserves file identifiers 0, 1, and 2 for standard input, standard output (the screen), and standard error, respectively. When fopen successfully opens a file, it returns a file identifier greater than or equal to 3.

message

A system-dependent error message when fopen cannot open the specified file. Otherwise, an empty string.

fIDs

Row vector containing the identifiers for all open files, except the identifiers reserved for standard input, output, and error. The number of elements in the vector is equal to the number of open files.

filename

Name of the file associated with the specified fileID.

permission

The permission that fopen assigned to the file specified by fileID.

machineformat

The value of machineformat that fopen used when it opened the file specified by fileID.

encoding

The character encoding scheme that fopen associated with the file specified by fileID.

The value that fopen returns for encoding is a standard character encoding scheme name. It is not always the same as the encoding argument that you used in the call to fopen to open the file.

Examples

Open a file. Pass the file identifier, fid, to other file I/O functions to read data and close the file.

fid = fopen('fgetl.m');

tline = fgetl(fid);
while ischar(tline)
    disp(tline);
    tline = fgetl(fid);
end

fclose(fid);
 

Create a prompt to request the name of a file to open. If fopen cannot open the file, display the relevant error message.

fid = -1;
msg = '';
while fid < 0 
   disp(msg);
   filename = input('Open file: ', 's');
   [fid,msg] = fopen(filename);
end
 

Open a file to write Unicode® characters to a file using the Shift-JIS character encoding scheme:

fid = fopen('japanese_out.txt', 'w', 'n', 'Shift_JIS');

See Also

fclose | feof | ferror | fprintf | fread | fscanf | fseek | ftell | fwrite

  

 

Free MATLAB Interactive Kit

Explore how to use MATLAB to make advancements in engineering and science.


Download free kit

Trials Available

Try the latest version of MATLAB and other MathWorks products.


Get trial software
 © 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS