archived-doc-de/reference/filesystem/functions/fopen.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 18bac8389b98d513c89e965000086acfcdfdd0a9 Maintainer: khp Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: d579464d52f6b579db3de974cd319c99dd3d71aa Reviewer: samesch -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fopen">
 <refnamediv>
  <refname>fopen</refname>
  <refpurpose>Öffnet eine Datei oder URL</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>resource</type><type>false</type></type><methodname>fopen</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam><type>string</type><parameter>mode</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>fopen</function> bindet eine benannte Ressource, die durch
   <parameter>filename</parameter> spezifiziert wurde, an einen Stream.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Wenn <parameter>filename</parameter> die Form "schema://..." hat,
       wird angenommen, dass es sich hier um eine URL handelt, und PHP sucht
       nach einem Protokollhandler (auch als Wrapper bekannt) für dieses
       Schema. Sind keine Wrapper für dieses Protokoll registriert, gibt PHP
       einen Hinweis aus, um Ihnen zu helfen, mögliche Probleme in Ihrem
       Skript zu erkennen, und fährt dann fort, als ob
       <parameter>filename</parameter> eine reguläre Datei spezifiziert.
      </para>
      <para>
       Ist PHP zu dem Schluss gekommen, dass <parameter>filename</parameter>
       eine lokale Datei spezifiziert, wird es versuchen, einen Stream
       an dieser Datei zu öffnen. Die Datei muss für PHP zugreifbar sein,
       weshalb Sie sicherstellen müssen, dass die Dateirechte diesen
       Zugriff ermöglichen. Wenn Sie
       <link linkend="ini.open-basedir">open_basedir</link> aktiviert haben,
       können weitere Einschränkungen gelten.
      </para>
      <para>
       Kam PHP zum Schluss, dass es sich bei <parameter>filename</parameter>
       um ein registriertes Protokoll handelt, und ist dieses Protokoll
       als eine Netzwerk-URL registriert, prüft PHP, ob
       <link linkend="ini.allow-url-fopen">allow_url_fopen</link> aktiviert
       ist. Ist es nicht aktiviert, gibt PHP eine Warnung aus und der Aufruf
       von <function>fopen</function> scheitert.
      </para>
      <note>
       <para>
        Die Liste der unterstützten Protokolle ist unter
        <xref linkend="wrappers"/> zu finden. Einige Protokolle (auch als
        <literal>Wrapper</literal> bezeichnet) unterstützen
        <literal>context</literal> und/oder &php.ini;-Optionen. Eine Liste der
        verfügbaren Optionen finden Sie auf den Handbuchseiten zum verwendeten
        Protokoll (&zb; die &php.ini;-Option <literal>user_agent</literal>,
        die vom <literal>http</literal>-Wrapper verwendet wird).
       </para>
      </note>
      <para>
       Es ist darauf zu achten, unter Windows alle Backslash-Zeichen, die in
       Pfaden genutzt werden, zu maskieren oder Schrägstriche (Slashes) zu
       nutzen.
       <informalexample>
        <programlisting role="php">
<![CDATA[
<?php
$handle = fopen("c:\\verzeichnis\\ressource.txt", "r");
?>
]]>
        </programlisting>
       </informalexample>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       Der Parameter <parameter>mode</parameter> spezifiziert den Zugriffstyp,
       der vom Stream gefordert wird. Es kann einer der folgenden sein:
       <table>
        <title>
         Eine Liste der möglichen Modi von <function>fopen</function> mittels
         <parameter>mode</parameter>
        </title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry><parameter>mode</parameter></entry>
           <entry>Beschreibung</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><literal>'r'</literal></entry>
           <entry>
            Nur zum Lesen geöffnet; platziere den Dateizeiger auf den
            Dateianfang.
           </entry>
          </row>
          <row>
           <entry><literal>'r+'</literal></entry>
           <entry>
            Zum Lesen und Schreiben geöffnet; platziere den Dateizeiger auf
            den Dateianfang.
           </entry>
          </row>
          <row>
           <entry><literal>'w'</literal></entry>
           <entry>
            Nur zum Schreiben geöffnet; platziere den Dateizeiger auf den
            Dateianfang und kürze die Datei auf eine Länge von 0. Existiert
            die Datei nicht, versuche, diese zu erzeugen.
           </entry>
          </row>
          <row>
           <entry><literal>'w+'</literal></entry>
           <entry>
            Zum Schreiben und Lesen geöffnet; ansonsten verhält es sich wie
            <literal>'w'</literal>..
           </entry>
          </row>
          <row>
           <entry><literal>'a'</literal></entry>
           <entry>
            Nur zum Schreiben geöffnet; platziere den Dateizeiger auf das
            Dateiende. Existiert die Datei nicht, versuche, diese zu erzeugen.
            In diesem Modus ist <function>fseek</function> wirkungslos; beim
            Schreiben wird immer angehängt.
           </entry>
          </row>
          <row>
           <entry><literal>'a+'</literal></entry>
           <entry>
            Zum Schreiben und Lesen geöffnet; platziere den Dateizeiger auf
            das Dateiende. Existiert die Datei nicht, versuche, diese zu
            erzeugen. In diesem Modus wirkt sich <function>fseek</function>
            nur auf die Leseposition aus; beim Schreiben wird immer angehängt.
           </entry>
          </row>
          <row>
           <entry><literal>'x'</literal></entry>
           <entry>
            Erzeuge und öffne nur zum Schreiben; platziere den Dateizeiger auf
            den Dateianfang. Falls die Datei schon existiert, wird der
            <function>fopen</function>-Aufruf fehlschlagen, indem er &false;
            zurückgibt und dem einen Fehler der Stufe
            <constant>E_WARNING</constant> auslöst. Existiert die Datei nicht,
            versuche, diese zu erzeugen. Dies ist zur Angabe der
            <literal>O_EXCL|O_CREAT</literal>-Flags für den darunterliegenden
            <literal>open(2)</literal>-Systemaufruf äquivalent.
           </entry>
          </row>
          <row>
           <entry><literal>'x+'</literal></entry>
           <entry>
            Erzeuge und öffne zum Schreiben und Lesen; ansonsten ist das
            Verhalten gleich wie bei <literal>'x'</literal>.
           </entry>
          </row>
          <row>
           <entry><literal>'c'</literal></entry>
           <entry>
            Öffne die Datei nur zum Schreiben. Wenn die Datei nicht existiert,
            wird diese erzeugt. Wenn sie existiert, wird sie weder gekürzt (im
            Gegensatz zu <literal>'w'</literal>), noch schlägt der Aufruf
            dieser Funktion fehl (wie dies mit <literal>'x'</literal> der Fall
            ist). Der Dateizeiger wird auf den Dateianfang platziert. Dies
            kann nützlich sein, wenn man eine "beratende" (kooperative) Sperre
            erhalten möchte (siehe <function>flock</function>), bevor man
            versucht, die Datei zu ändern, da die Nutzung von
            <literal>'w'</literal> die Datei kürzen könnte, bevor die Sperre
            erhalten wurde (falls das Kürzen gewünscht ist, kann
            <function>ftruncate</function> genutzt werden, nachdem die Sperre
            angefragt wurde).
           </entry>
          </row>
          <row>
           <entry><literal>'c+'</literal></entry>
           <entry>
            Öffne Datei zum Lesen und Schreiben; ansonsten ist das Verhalten
            gleich wie bei <literal>'c'</literal>.
           </entry>
          </row>
          <row>
           <entry><literal>'e'</literal></entry>
           <entry>
            Setzt das Flag close-on-exec für den geöffneten Datei-Deskriptor.
            Nur verfügbar, wenn PHP auf POSIX.1-2008-konformen System kompiliert
            wurde.
           </entry>
          </row>
          <row>
           <entry><literal>'n'</literal></entry>
           <entry>
            Setzt das Flag non-blocking flag für den geöffneten Datei-Deskriptor.
            Nur verfügbar, wenn PHP auf POSIX.1-2008-konformen System kompiliert
            wurde.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <note>
       <para>
        Verschiedene Betriebssysteme haben unterschiedliche Konventionen für
        das Zeilenende. Wenn Sie eine Textdatei schreiben und einen
        Zeilenumbruch einfügen möchten, müssen Sie das/die korrekte(n)
        Zeilenendezeichen für Ihr Betriebssystem nutzen. Unix-basierte Systeme
        nutzen <literal>\n</literal> als Zeilenendezeichen, Windows-basierte
        Systeme nutzen <literal>\r\n</literal> als Zeilenendezeichen und
        Macintosh-basierte Systeme (Mac OS Classic) nutzten
        <literal>\r</literal> als Zeilenendezeichen.
       </para>
       <para>
        Wenn Sie die falschen Zeilenendezeichen beim Schreiben Ihrer Dateien
        nutzen, kann es sein, dass andere Anwendungen, die diese Dateien
        öffnen, "seltsam aussehen".
       </para>
       <para>
        Windows bietet ein Übersetzungs-Flag (<literal>'t'</literal>) fur den
        Textmodus an, das <literal>\n</literal> transparent in
        <literal>\r\n</literal> übersetzt, wenn mit der Datei gearbeitet wird.
        Andererseits kann auch <literal>'b'</literal> genutzt werden, um den
        Binärmodus zu erzwingen, der die Daten nicht übersetzt. Um diese Flags
        zu nutzen, wird entweder <literal>'b'</literal> oder
        <literal>'t'</literal> als das letzte Zeichen des Parameters
        <parameter>mode</parameter> angegeben.
       </para>
       <para>
        Der Standard-Übersetzungsmodus ist <literal>'b'</literal>. Es kann der
        Modus <literal>'t'</literal> genutzt werden, wenn mit Textdateien
        gearbeitet wird und <literal>\n</literal> verwendet wird, um die
        Zeilenenden im Skript zu begrenzen, aber erwartet wird, dass die
        Dateien mit Anwendungen wie etwa alten Versionen von Notepad lesbar
        sind. Ansonsten sollte <literal>'b'</literal> genutzt werden.
       </para>
       <para>
        Wird beim Arbeiten mit binären Dateien das Flag 't' angegeben, können
        seltsame Probleme mit den Daten auftreten, einschließlich zerstörter
        Bilddateien und merkwürdiger Probleme mit
        <literal>\r\n</literal>-Zeichen.
       </para>
      </note>
      <note>
       <para>
        Aus Portabilitätsgründen wird ebenfalls dringend empfohlen, dass Code,
        der den Modus <literal>'t'</literal> nutzt oder sich darauf verlässt,
        so umgeschrieben wird, dass stattdessen die korrekten Zeilenendungen
        und der Modus <literal>'b'</literal> genutzt werden.
       </para>
      </note>
      <note>
       <simpara>
        Der Parameter <parameter>mode</parameter> wird bei den Stream-Wrappern
        <filename>php://output</filename>, <filename>php://input</filename>,
        <filename>php://stdin</filename>, <filename>php://stdout</filename>,
        <filename>php://stderr</filename> und <filename>php://fd</filename>
        ignoriert.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>use_include_path</parameter></term>
     <listitem>
      <para>
       Der optionale dritte Parameter <parameter>use_include_path</parameter>
       kann auf &true; gesetzt werden, wenn auch im
       <link linkend="ini.include-path">include_path</link> nach der Datei
       gesucht werden soll.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>context</parameter></term>
     <listitem>
      &note.context-support;
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Gibt bei Erfolg eine Dateizeiger-Ressource zurück. &return.falseforfailure;
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &fs.emits.warning.on.failure;
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.0.16, 7.1.2</entry>
       <entry>
        Die Option <literal>'e'</literal> wurde hinzugefügt.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>fopen</function>-Beispiele</title>
    <programlisting role="php">
<![CDATA[
<?php
$handle = fopen("/home/rasmus/file.txt", "r");
$handle = fopen("/home/rasmus/file.gif", "wb");
$handle = fopen("http://www.example.com/", "r");
$handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &warn.ssl-non-standard;
  <note>
   <para>
    Wenn die Servermodul-Version von PHP wird verwendet wird und beim Lesen
    und Schreiben von Dateien Probleme auftreten, ist sicherzustellen, dass
    die Dateien und Verzeichnisse, die genutzt werden, für den Server-Prozess
    zugänglich sind.
   </para>
  </note>
  <note>
   <para>
    Diese Funktion kann auch dann funktionieren, wenn
    <parameter>filename</parameter> ein Verzeichnis ist. Im Zweifelsfall
    sollte vor dem Aufruf von <function>fopen</function> mit
    <function>is_dir</function> geprüft werden, ob
    <parameter>filename</parameter> eine Datei oder ein Verzeichnis ist.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><xref linkend="wrappers"/></member>
    <member><function>fclose</function></member>
    <member><function>fgets</function></member>
    <member><function>fread</function></member>
    <member><function>fwrite</function></member>
    <member><function>fsockopen</function></member>
    <member><function>file</function></member>
    <member><function>file_exists</function></member>
    <member><function>is_readable</function></member>
    <member><function>stream_set_timeout</function></member>
    <member><function>popen</function></member>
    <member><function>stream_context_create</function></member>
    <member><function>umask</function></member>
    <member><classname>SplFileObject</classname></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->