Quantcast

Documentation Center

  • Trial Software
  • Product Updates

fopen

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

fopen(filename | TempFile, <Read | Write | Append>, <Bin | Text | Raw>, <Encoding = "encodingValue">)

Description

fopen(filename, format) opens an existing file for reading in the specified format. An error is raised if no file with the specified name is found or the format of the file does not coincide with the specified format. If the file is in gzip-compressed format and its name ends in ".gz", it will be transparently uncompressed upon reading.

fopen(filename) opens an existing file for reading. The file must hold data in text or MuPAD® binary format (optionally compressed), fopen automatically identifies the file format in this case. The file must not be used as raw file.

fopen(filename, mode, format) opens the file for writing in the specified format if the mode is given as Read or Append. If no file with the specified name exists, a new file is created. If the filename ends in ".gz", all data written to the file will be transparently compressed in gzip compatible format.

fopen(TempFile, format) creates and opens a temporary file for writing in the specified format. The option Read and Append are not allowed in this case. If no format is given, Bin is used. Use fname to query the actual name and location of the temporary file. Cf. Example 3.

fopen(..., Encoding = "encodingValue") uses the specified encoding. For supported encodings, see Options. You can use this option with the previously specified syntaxes for text files.

In write mode (using one of the options Write or Append), the environment variable WRITEPATH is considered if no temporary file is created. If it has a value, a new file is created (or an existing file is searched for) in the corresponding folder. Otherwise, it is created/searched for in the "working folder."

Note that the meaning of "working folder" depends on the operating system. On Windows® systems and on Mac OS X systems, the "working folder" is the folder where MATLAB® is installed. On UNIX® systems, it is the current working folder in which MATLAB was started. When started from a menu or desktop item, this is typically the user's home folder.

    Note:   In read mode, fopen does not search for files in the folders given by READPATH and the library path.

A temporary file is created in a special folder. This folder and the name of the file are system dependent.

Also absolute path names are processed by fopen.

The file descriptor returned by fopen can be used by various functions such as fname, fclose, fread, fprint, read, write etc.

A file opened by fopen should be closed by fclose after use. This holds also for temporary files.

fopen accepts its arguments in any order, not only in the order used above.

Environment Interactions

The function is sensitive to the environment variable WRITEPATH when creating files that are not temporary (temporary files are created via TempFile). If WRITEPATH has a value, in write mode (using the options Write or Append), the file is created in the corresponding folder. Otherwise, the file is created in the "working folder." A temporary file is created in a special folder.

When using Write or Append, fopen creates a new file if no file under the given name exists.

Examples

Example 1

Open the file test for writing. With the option Write, it is not necessary that the file test exists. By default, the file is opened as a binary file:

fid := fopen("test", Write):

Write a string to the file and close it:

fprint(fid, "a string"):
fclose(fid):

Append another string to the file:

fid := fopen("test", Append):
fprint(fid, "another string"):
fclose(fid):

The binary file cannot be opened as a text file for appending data:

fid := fopen("test", Append, Text)

However, it may be opened as a text file with the option Write. The existing binary file is overwritten with a text file:

fid := fopen("test", Write, Text):
fclose(fid):
delete fid:

Example 2

fopen fails to open non-existing files for reading. Here, assume the file "xyz" does not exist:

n := fopen("xyz")

Assume the file "test" created in Example 1 exists. It can be opened for reading successfully:

n := fopen("test")

fclose(n):
delete n:

Example 3

Open a temporary file, write 10 binary data bytes into it and close it. fname is used to query the name of the file:

fd := fopen(TempFile, Raw):
writebytes(fd, [i $ i=1..10]):
fn := fname(fd):
fclose(fd):
fn

Re-open the file and read the data:

fd := fopen(fn, Read, Raw):
readbytes(fd);

fclose(fd):
delete fd, fn:

Example 4

To specify the encoding to read and write data, use Encoding. The Encoding option applies only to text files that are opened using a file name and not a file descriptor. Create a temporary file and write the string "abcäöü" in the encoding "UTF-8":

fid := fopen(TempFile, Text, Write, Encoding="UTF-8"):
file := fname(fid):
fprint(Unquoted, fid, "abcäöü"):
fclose(fid):

Use ftextinput to read the data with the specified encoding:

ftextinput(file, Encoding="UTF-8")

If you do not specify an encoding, the default system encoding is used. Thus, your output might vary from that shown next. Characters unrecognized by the default system encoding are replaced by the default substitution character for that encoding:

fid := fopen(TempFile, Text, Write):
file := fname(fid):
fprint(Unquoted, fid, "abcäöü"):
fclose(fid):
ftextinput(file)

Parameters

filename

The name of a file: a character string or the flag TempFile

Options

TempFile

fopen creates a temporary file in the systems "temp" folder. The name of this file can be queried using fname.

Append, Read, Write

With Read, the file is opened for reading; with Write or Append, it is opened for writing. If a file opened for writing does not yet exist, it is created. With Write, existing files are overwritten. With Append, new data may be appended to an existing file. Note that in the Append mode, the specified format must coincide with the format of the existing file; otherwise, the file cannot be opened and fopen returns FAIL. If the flag TempFile is given, the default mode is Write. Otherwise, the default mode is Read.

Bin, Raw, Text

With Bin, the data is stored in MuPAD internal binary format. With Text, the data may be strings or MuPAD objects stored as text. Newlines are handled according to the conventions of the operating system at hand. With Raw, the data is interpreted as binary machine numbers. See the functions readbytes and writebytes.

If the mode is Read or Append, the default is the format of the data in the existing file. If the mode is Write, the default is Bin.

Encoding

This option lets you specify the character encoding to use. The allowed encodings are:

"Big5"

"ISO-8859-1"

"windows-932"

"EUC-JP"

"ISO-8859-2"

"windows-936"

"GBK"

"ISO-8859-3"

"windows-949"

"KSC_5601"

"ISO-8859-4"

"windows-950"

"Macintosh"

"ISO-8859-9"

"windows-1250"

"Shift_JIS"

"ISO-8859-13"

"windows-1251"

"US-ASCII"

"ISO-8859-15"

"windows-1252"

"UTF-8"

 

"windows-1253"

  

"windows-1254"

  

"windows-1257"

The default encoding is system dependent. If you specify the encoding incorrectly, characters might read incorrectly. Characters unrecognized by the encoding are replaced by the default substitution character for the specified encoding.

Encodings not listed here can be specified but might not produce correct results.

Return Values

a positive integer: the file descriptor. FAIL is returned if the file cannot be opened.

See Also

MuPAD Functions

Was this topic helpful?