(octave.info)Opening and Closing Files

---

Next: Simple Output Up: C-Style I/O Functions

---

Enter node , (file) or (file)node

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, MSG] = fopen (...)
 -- : FID_LIST = fopen ("all")
 -- : [FILE, MODE, ARCH] = 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.) and architecture
     interpretation (IEEE big endian, IEEE little endian, etc.), 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 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.

     However, conversions are currently only supported for ‘native’,
     ‘ieee-be’, and ‘ieee-le’ formats.

     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: Note: fclose, Note: fgets, Note:
     fgetl, Note: fscanf, Note: fread,
     Note: fputs, Note: fdisp, *note fprintf:
     XREFfprintf, Note: fwrite, Note: fskipl,
     Note: fseek, Note: frewind, *note ftell:
     XREFftell, Note: feof, Note: ferror, Note:
     fclear, Note: fflush, *note freport:
     XREFfreport, Note: 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: Note: fopen, Note: fflush, Note:
     freport.

 -- : is_valid_file_id (FID)
     Return true if FID refers to an open file.

     See also: Note: freport, Note: fopen.