Products & Services Solutions Academia Support User Community Company

Learn more about MATLAB   

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.

Inputs

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. Specify machineformat to:

  • Read a file created on a different system.

  • Read bits in a particular order.

  • Create a file for use on a different system.

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.

encoding

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

Possible values are:

'Big5'

'ISO-8859-1'

'windows-932'

'EUC-JP'

'ISO-8859-2'

'windows-936'

'GBK'

'ISO-8859-3'

'windows-949'

'Shift_JIS'

'ISO-8859-4'

'windows-950'

'US-ASCII'

'ISO-8859-9'

'windows-1250'

'UTF-8'

'ISO-8859-13'

'windows-1251'

 

'ISO-8859-15'

'windows-1252'

  

'windows-1253'

  

'windows-1254'

  

'windows-1257'

Default: system-dependent

Outputs

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 | ferror

Related Links

  

fminsearchfminsearch fopen (serial)fopen (serial)

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit

 © 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS