.. highlightlang:: us

.. index:: fopen

.. _fopen:

fopen
=====

.. us.tag  fopen ENGLISH ffiles Changed500

:ref:`fopen` opens a file.

.. function::  fh = fopen(ssFileName, ssMode)
    fh = fopen(ssFileName, ssMode, nByteOrder)

.. us.return

**Return Value**

*fh* is a file handle.

.. us.params

**Parameters**

.. uparam:: ssFileName

   Path name of file.

.. uparam:: ssMode

   Type of access permitted. The character string *ssMode* specifies the type of
   access requested for the file as follows:

   .. list-table::
      :header-rows: 1

      * - Value
        - Meaning
      * - ``"r"``
        - Opens the file for reading. If the file does not exist or cannot be
          found, the fopen function returns 0.
      * - ``"w"``
        - Opens an empty file for writing. If the file exists, its contents are
          destroyed.
      * - ``"a"``
        - Opens the file for writing at the end of the file (appending); creates
          the file first if it doesn't exist.
      * - ``"r+"``
        - Opens the file for both reading and writing. (The file must exist.)
      * - ``"w+"``
        - Opens an empty file for both reading and writing. If the given file
          exists, its contents are destroyed.
      * - ``"a+"``
        - Opens the file for reading and appending. If the given file doesn't
          exist, the file will be created.

   In addition to the above values, the following characters can be included in
   *ssMode* to specify the translation mode for newline characters:

   .. list-table::
      :header-rows: 1

      * - Value
        - Meaning
      * - ``"t"``
        - Open in text (translated) mode. In text mode, carriage return-line feed
          combinations are translated into single line feeds on input, and
          linefeed characters are translated to carriage return-line feed
          combinations on output. CTRL+Z is interpreted as an end-of-file
          character on input. In files opened for reading/writing with "a+",
          fopen checks for a CTRL+Z at the end of the file and removes it, if
          possible. Using fseek to move within a file that ends with a CTRL+Z
          may cause fseek to behave improperly near the end of the file.
      * - ``"b"``
        - Open in binary (untranslated) mode. Translations involving
          carriage-return and line feed characters are suppressed. If "t" or "b"
          is not given in mode, the default translation mode is "t". If "t" or
          "b" is prefixed to the argument, the function fails and returns NULL.

   If ``"t"`` or ``"b"`` is not specified the file will be opened in binary mode
   ``"b"``.  ``"t"`` or ``"b"`` must be specified at the end of the mode 
   parameter, for example "wt", otherwise the function fails and returns 0.

   The *ssMode* parameter can contain an optional flag, that controls how strings
   are handled (see :ref:`fwrite_char <fwrite>`, :ref:`fread_char <fread>` and
   :ref:`fprintf`).  Internally, UniPlot uses the UTF16-Format for strings. In
   this format a character uses 2 bytes. 

   .. list-table::
      :header-rows: 1

      * - Value
        - Meaning
      * - ``"none"``
        - Read and write only the low order byte of a string.
      * - ``"ansi"``
        - Read and write ANSI (1 byte).
      * - ``"utf-8"``
        - Read and write UTF-8.
      * - ``"utf-16"``
        - Read and write UTF-16 big endian (Motorola Byte Order).
      * - ``"utf-16le"``
        - Read and write UTF-16 little endian (Intel Byte Order).

   The code ccs (coded character set) must be used as in the following example::

      fopen("c:/myfile.txt", "wt, ccs=ansi");

   The byte-order in the *nByteOrder* parameter has no effect on the coding.
   If the file is opened with read access and the file contains a BOM (Byte
   Order Mark) at the beginning of the file and ``ccs`` is not set to none, the
   coding of the BOM is used and the ``ccs`` element is ignored. 

   List of BOMs:

   .. list-table::
      :header-rows: 1

      * - Bytes
        - Encoding Form
      * - EF BB BF
        - UTF-8
      * - FE FF
        - UTF-16, big-endian
      * - FF FE
        - UTF-16, little-endian
      * - 00 00 FE FF
        - UTF-32, big-endian (not supported)
      * - FF FE 00 00
        - UTF-32, little-endian (not supported)

.. uparam:: nByteOrder

   *nByteOrder* specifies the byte order.

   .. list-table::
      :header-rows: 1

      * - Value
        - Meaning
      * - LITTLE_ENDIAN (1)
        - Little endian byte-order (e.g. Intel Pentium). This is the default
          value if the function is called without this parameter
      * - BIG_ENDIAN (2)
        - Big endian byte-order (e.g. Motorola CPU's).

.. us.example

**Example**

Open a binary file for reading and read 100 shorts

::

   fh = fopen("c:/test.bin", "rt");
   rvValues = fread(fh, "short", 100); // reads 100 short values
   fclose(fh);

.. us.example

**Example**

Open a binary file:

::

   fh = fopen("c:/test.bin", "r");
   rvValues = fread(fh, "short", 100); // reads 100 short values
   fclose(fh);

.. us.example

**Example**

::

   fh = fopen("c:/test.txt", "w");
   a = rand(10,10);
   fprintf(fh, "%10.2f\r\n", a);
   fclose(fh);
   EdCreate("c:/test.txt");

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - 5.0.0
     - Parameter *ssMode* changed.

.. seealso::
   :ref:`overview-binary-and-text-files`,
   :ref:`fclose`,
   :ref:`fprintf`,
   :ref:`fwrite`,
   :ref:`fread`,
   :ref:`fshow`,
   :ref:`feof`

:sub:`id-83421`