MATLAB^®

fopen - Open file, or obtain information about open files

Syntax

fid = fopen(filename) fid = fopen(filename, permission) fid = fopen(filename, permission, machineformat) fid = fopen(filename, permission, machineformat, encoding) [fid, message] = fopen(filename, ...) fids = fopen('all') [filename, permission, machineformat, encoding] = fopen(fid)

Description

fid = fopen(filename) opens the file filename for binary read access. The filename argument is a string enclosed in single quotation marks, and can include a full path or a partialpath. On UNIX systems, if you begin filename with '~/' or '~username/', fopen expands the path to the current or specified user's home directory, respectively.

Output value fid is a scalar MATLAB integer that you use as a file identifier for all subsequent low-level file input/output routines. If fopen cannot open the file, it returns -1. MATLAB reserves file identifiers 0, 1, and 2 for standard input, standard output, and standard error, respectively.

fid = fopen(filename, permission) opens the file filename with the specified permission. For a complete list, see Permission Values.

fid = fopen(filename, permission, machineformat) opens the file with the specified permission. In subsequent calls to fread or fwrite, the functions read or write the data according to the specified machineformat. For more information, see Machine Format Values.

fid = fopen(filename, permission, machineformat, encoding) opens the specified file using the specified permission and machineformat. encoding specifies the character encoding scheme associated with the file (such as 'UTF-8', 'latin1', 'US-ASCII', or 'Shift_JIS'). For common names and aliases, see the Web site http://www.iana.org/assignments/character-sets.

If you do not specify encoding, or you set it to the empty string, (''), fopen uses the MATLAB default (system-dependent) encoding scheme.

[fid, message] = fopen(filename, ...) opens a file as above. If fopen cannot open the file, fid equals -1 and message contains a system-dependent error message. If fopen successfully opens a file, message contains an empty string ('').

fids = fopen('all') returns a row vector containing the file identifiers of all open files, not including 0, 1, and 2 (standard input, output, and error). The number of elements in the vector is equal to the number of open files.

[filename, permission, machineformat, encoding] = fopen(fid) returns the filename, permission, machineformat, and encoding values that fopen used when it opened the file associated with identifier fid. fopen does not read information from the file to determine these output values. An invalid fid returns empty strings for all output arguments.

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

Remarks

Binary and Text Modes

On UNIX systems, binary and text modes are the same.

On Windows systems, binary and text modes are different. If you are unsure which mode is best for your file, use binary mode. By default, fopen opens files for binary read access.

In binary mode, read and write operations process all characters in the same manner. In text mode:

Read operations that encounter a carriage return followed by a newline character remove the carriage return from the input.
Write operations insert a carriage return before any newline character in the output.

To open a file in text mode, specify the permission using one of the listed Permission Values, and attach the letter 't'. For example, use 'rt' or 'wt+'.

Permission Values

Use the permission specifiers below to read or write in binary mode. For more information, see Binary and Text Modes.

Permission	Description
`'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.)

If you call fopen with the permission set to 'r' or 'r+', and fopen cannot find the filename in the current working directory, fopen also searches for the file along the MATLAB search path. Otherwise, fopen creates a new file in the current directory.

Note If you open a file in update mode (with a permission value that includes '+'), you must call fseek or frewind between read and write operations. For example, you cannot call fread followed by fwrite, or fwrite followed by fread, unless you call fseek or frewind between them.

Machine Format Values

By default, fopen sets machineformat to the format your system uses ('n'). Possible values, based on IEEE^® floating point formats, are:

`'n'` or `'native'`	The format your system uses
`'b'` or `'ieee-be'`	Big-endian byte ordering
`'l'` or `'ieee-le'`	Little-endian byte ordering
`'s'` or `'ieee-be.l64'`	Big-endian byte ordering, 64–bit data type
`'a'` or `'ieee-le.l64'`	Little-endian byte ordering, 64–bit data type

On all systems, the fread or fwrite functions observe the specified big-endian or little-endian ordering even when reading or writing bits.

Examples

Use fopen to open a file. Pass the fid to other file I/O functions to read data and then close the file.

fid = fopen('fgetl.m');

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

fclose(fid);