## `fopen` -- open a file

#### Introduction

`fopen``(filename)` opens the file with the name `filename`.

#### Call(s)

`fopen(filename)`
`fopen( <format,> filename, writemode)`

#### Parameters

`filename` | - | the name of a file: a character string

#### Options

`writemode` | - | either Write or Append. With both options, the file is opened for writing. If no file by the name `filename` exists, a new file is created. With Write, existing files are overwritten. With Append, new data may be appended to an existing file via the functions `fprint` or `write`. 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`.
`format` | - | the write format: either Bin or Text. With Bin, the data are stored in MuPAD's binary format. With Text, standard ASCII format is used. The default is Bin.

#### Returns

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

#### Side Effects

The function is sensitive to the environment variable `WRITEPATH`. If this variable has a value, in write mode (using the options Write or Append), the file is created in the corresponding directory. Otherwise, the file is created in the ``working directory''.

#### Related Functions

`fclose`, `finput`, `fprint`, `fread`, `ftextinput`, `pathname`, `print`, `protocol`, `read`, `READPATH`, `write`, `WRITEPATH`

#### Details

- `fopen``(filename)` opens an existing file for reading. `fopen` automatically identifies the file as a text file or as a binary file. An error is raised if no file with the specified name is found.
- `fopen``( <format,> filename, writemode)` opens the file for writing in the specified format. If no file with the specified name exists, a new file is created.
- In write mode (using one of the options Write or Append), the environment variable `WRITEPATH` is considered. If it has a value, a new file is created (or an existing file is searched for) in the corresponding directory. Otherwise, it is created/searched for in the ``working directory''.

  Note that the ``working directory'' depends on the operating system. On Windows systems, it is the folder, where MuPAD is installed. On UNIX or Linux systems, the ``working directory'' is the directory where MuPAD was started.

  In read mode, `fopen` does not search for files in the directories given by `READPATH` and `LIBPATH`.

  On the Macintosh, an empty file name may be given. In this case, a dialog box is opened in which the user can choose a file. Further, on the interactive level, MacMuPAD warns the user if an existing file is about to be overwritten.

  Also absolute path names are processed by `fopen`.

- The file descriptor returned by `fopen` can be used by various functions such as `fclose`, `fread`, `fprint`, `read`, `write` etc.
- A file opened by `fopen` should be closed by `fclose` after use.
- `fopen` is a function of the system kernel.

#### Example 1

We 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:

    >> n := fopen("test", Write)

                                        17

We write a string to the file and close it:

    >> fprint(n, "a string"): fclose(n):

We append another string to the file:

    >> n := fopen("test", Append)

                                        18

    >> fprint(n, "another string"): fclose(n):

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

    >> n := fopen(Text, "test", Append)

                                       FAIL

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

    >> n := fopen(Text, "test", Write)

                                        19

    >> fclose(n): delete n:

#### Example 2

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

    >> n := fopen("xyz")

                                       FAIL

We assume that the file `test` created in example 1 exists. It can be opened for reading successfully:

    >> n := fopen("test")

                                        20

    >> fclose(n): delete n:

#### Changes

- no changes

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000