.. highlightlang:: us

.. index:: fopen

.. _fopen:

fopen
=====

.. us.tag  fopen GERMAN ffiles Changed500

:ref:`fopen` öffnet eine Datei zum Lesen oder Schreiben.

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

.. us.return

**Returnwert**

*fh* ist eine Zugriffsnummer.

.. us.params

**Parameter**

.. uparam:: ssFileName

   *ssFileName* ist der vollständige Name der Datei.

.. uparam:: ssMode

   *ssMode* ist ein Stringskalar, der beschreibt wie die Datei geöffnet werden
   soll.

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

      * - Wert
        - Bedeutung
      * - ``"r"``
        - Öffnet die Datei zum Lesen. Falls die Datei nicht existiert oder nicht 
          gefunden werden kann, schlägt der Aufruf von fopen fehl.
      * - ``"w"``
        - Öffnet die Datei zum Schreiben. Falls die angegebene Datei bereits
          existiert, wird der Inhalt der Datei gelöscht.
      * - ``"a"``
        - Öffnet eine Datei zum Schreiben an das Ende der Datei (appending).
          Falls die Datei nicht existiert, wird sie erzeugt.
      * - ``"r+"``
        - Öffnet eine Datei zum Lesen und Schreiben. Die Datei muss existieren.
      * - ``"w+"``
        - Öffnet eine leere Datei zum Lesen und Schreiben. Falls die Datei
          existiert, wird sie gelöscht.
      * - ``"a+"``
        - Öffnet eine Datei zum Lesen und Anhängen (appending). Falls die Datei
          nicht existiert, wird sie erzeugt.

   Zusätzlich zu den oben angegebenen Werten können die folgenden Werte dem
   Parameter *ssMode* zugefügt werden, um festzulegen, wie das "newline"-Zeichen
   interpretiert werden soll.

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

      * - Wert
        - Bedeutung
      * - ``"t"``
        - Öffnet die Datei im Text-Mode. Im Text-Mode wird die 
          carriage return-linefeed (``\r\n``)-Kombination beim Lesen als
          einfaches  newline-Zeichen (\n) interpretiert. Beim Schreiben werden
          einfache newline-Zeichen als carriage return-linefeed-Kombinationen
          ausgegeben.
      * - ``"b"``
        - Öffnet die Datei im Binär-Mode. Es werden keine Umsetzungen durchgeführt.

   Falls ``"t"`` oder ``"b"`` nicht spezifiziert werden, wird die Datei im
   Binärmode geöffnet (``"b"``). Falls ``"t"`` oder ``"b"`` als  Prefix des
   Arguments verwendet werden, schlägt die Funktion fehl und liefert den Wert 0.

   Im Parameter *ssMode* kann zusätzlich noch ein Flag angegeben werden, das
   Einfluß auf die Verarbeitung von Zeichenketten hat (siehe
   :ref:`fwrite_char <fwrite>`, :ref:`fread_char <fread>` und :ref:`fprintf`). 
   Intern werden Zeichenketten im UTF16-Format verarbeitet. Ein Zeichen 
   benötigt 2 Bytes.

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

      * - Wert
        - Bedeutung
      * - ``"none"``
        - Schreibt und liest nur das untere Byte einer Zeichenkette.
      * - ``"ansi"``
        - Schreibt und liest ANSI (1 byte).
      * - ``"utf-8"``
        - Schreibt und liest UTF-8.
      * - ``"utf-16"``
        - Schreibt und liest UTF-16 big endian (Motorola Byte Order).
      * - ``"utf-16le"``
        - Schreibt und liest UTF-16 little endian (Intel Byte Order).

   Die Kodierung (ccs bedeutet coded character set) wird wie im folgenden
   Beispiel angegeben:

   ::

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

   Die byte-Order im Parameter *nByteOrder* hat keinen Einfluß auf die Kodierung.
   Wenn die Datei zum Lesen geöffnet wird und die Datei enthält ein BOM (Byte
   Order Mark) am Anfang der Datei und es is nicht ``ccs=none`` angegeben, wird
   die Kodierung des BOMs verwendet und die Kodierung ccs wird ignoriert.
   Das BOM dient zur Markierung von Unicode-Dateien. Liste von 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 (nicht unterstützt von UniPlot)
      * - FF FE 00 00
        - UTF-32, little-endian (nicht unterstützt von UniPlot)

.. uparam:: nByteOrder

   *nByteOrder* gibt die byte-order an.

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

      * - Wert
        - Bedeutung
      * - LITTLE_ENDIAN (1)
        - Little endian byte-order (z. B. Intel Pentium). Dies ist der
          Default-Wert, falls *nByteOrder* nicht angegeben wird.
      * - BIG_ENDIAN (2)
        - Big endian byte-order (z. B. Motorola CPU).

.. us.example

**Beispiel**

Öffnet eine binäre Datei zum Lesen::

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

.. us.example

**Beispiel**

::

   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
     - Beschreibung
   * - 5.0.0
     - Änderung des Parameters *ssMode*.

.. seealso::
   :ref:`uberblick-binar--und-text-dateien`,
   :ref:`fclose`,
   :ref:`fprintf`,
   :ref:`fwrite`,
   :ref:`fread`,
   :ref:`fshow`,
   :ref:`feof`

:sub:`id-83421`