14.2.1 Opening and Closing Files

When reading data from a file it must be opened for reading first, and likewise when writing to a file. The fopen function returns a pointer to an open file that is ready to be read or written. Once all data has been read from or written to the opened file it should be closed. The fclose function does this. The following code illustrates the basic pattern for writing to a file, but a very similar pattern is used when reading a file.

filename = "myfile.txt";
fid = fopen (filename, "w");
# Do the actual I/O here…
fclose (fid);

: fid = fopen (name)

: fid = fopen (name, mode)

: fid = fopen (name, mode, arch)

: fid = fopen (name, mode, arch, encoding)

: [fid, msg] = fopen (…)

: fid_list = fopen ("all")

: [file, mode, arch, encoding] = fopen (fid)

Open a file for low-level I/O or query open files and file descriptors.

The first form of the fopen function opens the named file with the specified mode (read-write, read-only, etc.), architecture interpretation (IEEE big endian, IEEE little endian, etc.) and file encoding, and returns an integer value that may be used to refer to the file later. If an error occurs, fid is set to -1 and msg contains the corresponding system error message. The mode is a one or two character string that specifies whether the file is to be opened for reading, writing, or both. The encoding is a character string with a valid encoding identifier. This encoding is used when strings are read from or written to the file. By default, the same encoding specified for reading .m files is used for interpreting user files.

The second form of the fopen function returns a vector of file ids corresponding to all the currently open files, excluding the stdin, stdout, and stderr streams.

The third form of the fopen function returns information about the open file given its file id.

For example,

myfile = fopen ("splat.dat", "r", "ieee-le");

opens the file splat.dat for reading. If necessary, binary numeric values will be read assuming they are stored in IEEE format with the least significant bit first, and then converted to the native representation.

Opening a file that is already open simply opens it again and returns a separate file id. It is not an error to open a file several times, though writing to the same file through several different file ids may produce unexpected results.

The possible values of mode are

‘r’ (default)

Open a file for reading.

‘w’

Open a file for writing. The previous contents are discarded.

‘a’

Open or create a file for writing at the end of the file.

‘r+’

Open an existing file for reading and writing.

‘w+’

Open a file for reading or writing. The previous contents are discarded.

‘a+’

Open or create a file for reading or writing at the end of the file.

Append a "t" to the mode string to open the file in text mode or a "b" to open in binary mode. On Windows systems, text mode reading and writing automatically converts linefeeds to the appropriate line end character for the system (carriage-return linefeed on Windows). The default when no mode is specified is binary.

Additionally, you may append a "z" to the mode string to open a gzipped file for reading or writing. For this to be successful, you must also open the file in binary mode.

The parameter arch is a string specifying the default data format for the file. Valid values for arch are:

"native" or "n" (default)

The format of the current machine.

"ieee-be" or "b"

IEEE big endian format.

"ieee-le" or "l"

IEEE little endian format.

When opening a new file that does not yet exist, permissions will be set to 0666 - umask.

Compatibility Note: Octave opens files using buffered I/O. Small writes are accumulated until an internal buffer is filled, and then everything is written in a single operation. This is very efficient and improves performance. MATLAB, however, opens files using flushed I/O where every write operation is immediately performed. If the write operation must be performed immediately after data has been written then the write should be followed by a call to fflush to flush the internal buffer.

See also: fclose, fgets, fgetl, fscanf, fread, fputs, fdisp, fprintf, fwrite, fskipl, fseek, frewind, ftell, feof, ferror, fclear, fflush, freport, umask.

: fclose (fid)

: fclose ("all")

: status = fclose ("all")

Close the file specified by the file descriptor fid.

If successful, fclose returns 0, otherwise, it returns -1. The second form of the fclose call closes all open files except stdin, stdout, stderr, and any FIDs associated with gnuplot.

See also: fopen, fflush, freport.

: is_valid_file_id (fid)

Return true if fid refers to an open file.

See also: freport, fopen.