proc-open.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 6667724b8a42ba501172bc874dd1644a6744be0f Maintainer: sammywg Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: c1f8c2ea33c70f59557175e1a43af7153b1df565 Reviewer: samesch -->
<refentry xml:id="function.proc-open" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>proc_open</refname>
  <refpurpose>
   Führt ein Kommando aus und öffnet Dateizeiger für die Ein- und Ausgabe
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
   <methodsynopsis>
    <type class="union"><type>resource</type><type>false</type></type><methodname>proc_open</methodname>
    <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>command</parameter></methodparam>
    <methodparam><type>array</type><parameter>descriptor_spec</parameter></methodparam>
    <methodparam><type>array</type><parameter role="reference">pipes</parameter></methodparam>
    <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>cwd</parameter><initializer>&null;</initializer></methodparam>
    <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>env_vars</parameter><initializer>&null;</initializer></methodparam>
    <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
  <para>
   <function>proc_open</function> ist äquivalent zu <function>popen</function>,
   ermöglicht aber einen höheren Grad von Kontrolle über die Programmausführung.
  </para>

<!-- ptys are currently disabled in the sources
  <para>
   PHP 5 führt die PTY-Unterstützung für Systeme mit Unix98-PTYs ein. Dies
   erlaubt es Ihren Skripten, mit Applikationen zu interagieren, die erwarten,
   dass sie mit einem Terminal zu kommunizieren. Ein PTY funktioniert wie eine
   Pipe, ist aber bidirektional, daher müssen Sie keinen Lese-/Schreibmodus
   angeben. Das folgende Beispiel zeigt, wie ein PTY verwendet wird. Es ist zu
   beachten, dass nicht alle Filedescriptoren mit dem PTY verbunden sein
   müssen. Außerdem ist zu beachten, dass nur ein PTY erstellt wird, auch wenn
   PTY dreimal angegeben wird. In zukünftigen Versionen von PHP wird es
   möglich sein, mehr als die Funktionen Read und Write in Verbindung mit
   einem PTY zu nutzen.
  </para>
-->

 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>command</parameter></term>
     <listitem>
      <para>
       Das auszuführende Kommandozeile als &string;. Sonderzeichen müssen
       ordnungsgemäß maskiert und Argumente ggf. in Anführungszeichen
       eingeschlossen werden.
      </para>
      <note>
       <simpara>
        Unter <emphasis>Windows</emphasis> wird, falls
        <literal>bypass_shell</literal> in
        <parameter>options</parameter> nicht auf &true; gesetzt ist, das
        <parameter>command</parameter> mit dem Flag <literal>/c</literal> als
        <emphasis>nicht in Anführungszeichen eingeschlossene</emphasis>
        Zeichenkette (&dh; genau wie an <function>proc_open</function>
        übergeben) an <command>cmd.exe</command> übergeben (genauer gesagt an
        <literal>%ComSpec%</literal>). Dies kann dazu führen, dass
        <command>cmd.exe</command> die umschließenden Anführungszeichen von
        <parameter>command</parameter> entfernt (Details sind der Dokumentation
        von <command>cmd.exe</command> zu entnehmen), was zu unerwartetem und
        potentiell sogar gefährlichem Verhalten führen kann, da
        Fehlermeldungen von <command>cmd.exe</command> das übergebene
        <parameter>command</parameter> oder Teile davon enthalten können (siehe
        Beispiel weiter unten).
       </simpara>
      </note>
      <para>
       Von PHP 7.4.0 an kann <parameter>command</parameter> als &array; von
       Befehlsparametern übergeben werden. In diesem Fall wird der Prozess
       direkt gestartet (ohne Umweg über die Shell) und PHP kümmert sich um
       das nötige Maskieren der Argumente.
      </para>
      <note>
       <para>
        Unter Windows erfolgt die Argumentenmaskierung der &array;-Elemente
        unter der Annahme, dass das Parsen der Kommandozeile des
        auszuführenden Kommandos kompatibel ist mit dem Parsen der
        Kommandozeile durch die VC-Laufzeitumgebung.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>descriptor_spec</parameter></term>
     <listitem>
      <para>
       Ein indexiertes Array, in dem die Schlüssel die Descriptornummer
       repräsentieren und die Werte die Art und Weise, in der PHP die
       Descriptoren an die Child-Prozesse übergibt. 0 steht dabei für stdin, 1
       für stdout und 2 für stderr.
      </para>
      <para>
       Jedes Element kann sein:
       <simplelist>
        <member>
         Ein Array, das die Pipe beschreibt, die an den Prozess übergeben
         wird. Das erste Element ist der Descriptortyp, das zweite Element ist
         eine Option für den angegebenen Typ. Gültige Typen sind
         <literal>pipe</literal> (das zweite Element ist entweder
         <literal>r</literal>, um das Ende des Leseprozesses der Pipe an den
         Prozess zu übergeben, oder <literal>w</literal>, um das Ende des
         Schreibprozesses zu übergeben) und <literal>file</literal> (das
         zweite Element ist ein Dateiname). Es ist zu beachten, dass alles
         außer w wie r behandelt wird.
        </member>
        <member>
         Eine Streamressource, die einen echten Filedescriptor repräsentiert
         (&zb; geöffnete Dateien, Sockets, <constant>STDIN</constant>).
        </member>
       </simplelist>
      </para>
      <para>
       Die Filedescriptor-Nummern sind nicht limitiert auf 0, 1 und 2 - Sie
       können jede gültige Filedescriptor-Nummer angeben, die an den
       Kindprozess übergeben wird. Dies erlaubt es Ihrem Skript, mit anderen
       Skripten zu interagieren, die als "Co-Prozesse" laufen. Dies ist
       insbesondere dann nützlich, wenn Passwörter auf sichere Weise an
       Programme wie PGP, GPG und openssl übergeben werden sollen. Es ist
       ebenfalls nützlich, um Lesestatus-Informationen zu erhalten, die von
       diesen Programmen für zusätzliche Filedescriptoren ermittelt werden.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>pipes</parameter></term>
     <listitem>
      <para>
       Enthält ein numerisches Array von Dateizeigern, die der PHP-Seite jeder
       erstellten Pipe entsprechen.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>cwd</parameter></term>
     <listitem>
      <para>
       Das initiale Arbeitsverzeichnis des Kommandos. Dies muss ein
       <emphasis role="strong">absoluter</emphasis> Pfadname sein. Wenn Sie
       den Standardwert verwenden möchten (dies wäre das Arbeitsverzeichnis
       des aktuellen PHP-Prozesses), muss der Wert &null; sein.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>env_vars</parameter></term>
     <listitem>
      <para>
       Ein Array mit den Umgebungsvariablen für das auszuführende Kommando,
       oder &null;, wenn Sie die gleiche Umgebung wie der aktuelle PHP-Prozess
       nutzen wollen.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       Erlaubt Ihnen, zusätzliche Optionen anzugeben. Derzeit unterstützte
       Optionen sind:
       <simplelist>
        <member>
         <literal>suppress_errors</literal> (nur unter Windows): Unterdrückt
         Fehlermeldungen, die durch diese Funktion hervorgerufen werden, sofern
         der Wert auf &true; gesetzt wurde.
        </member>
        <member>
         <literal>bypass_shell</literal> (nur unter Windows): umgeht die
         <literal>cmd.exe</literal>-Shell, wenn der Wert auf &true; gesetzt
         wurde.
        </member>
        <member>
         <literal>blocking_pipes</literal> (nur unter Windows): erzwingt
         blockierende Pipes, wenn der Wert auf &true; gesetzt wurde.
        </member>
        <member>
         <literal>create_process_group</literal> (nur unter Windows):
         ermöglicht dem Kindprozess <literal>CTRL</literal> Ereignisse zu
         behandeln, wenn der Wert auf &true; gesetzt wurde.
        </member>
        <member>
         <literal>create_new_console</literal> (nur unter Windows): der neue
         Prozess hat eine neue Konsole anstatt die Konsole des Elternprozesses
         zu erben
        </member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Gibt eine Ressource zurück, die den Prozess repräsentiert, der unter
   Verwendung von <function>proc_close</function> freigegeben werden soll, wenn
   Sie ihn beenden. Im Fehlerfall wird &false; zurückgegeben.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   Wenn <parameter>command</parameter> ein Array ist, das nicht mindestens ein
   nicht-leeres Element enthält, wird seit PHP 8.3.0 ein
   <exceptionname>ValueError</exceptionname> ausgelöst.
  </simpara>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.3.0</entry>
       <entry>
        Ein <exceptionname>ValueError</exceptionname> wird ausgelöst, wenn
        <parameter>command</parameter> ein Array ist, das nicht mindestens ein
        nicht-leeres Element hat.
       </entry>
      </row>
      <row>
       <entry>7.4.4</entry>
       <entry>
        Die Option <literal>create_new_console</literal> wurde dem Parameter
        <parameter>options</parameter> hinzugefügt.
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        <function>proc_open</function> akzeptiert nun ebenfalls ein &array;
        für das <parameter>command</parameter>.
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        Die Option <literal>create_process_group</literal> wurde dem Parameter
        <parameter>options</parameter> hinzugefügt.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ein <function>proc_open</function>-Beispiel</title>
    <programlisting role="php">
<![CDATA[
<?php
$descriptorspec = array(
   0 => array("pipe", "r"),  // stdin ist eine Pipe, von der das Child liest
   1 => array("pipe", "w"),  // stdout ist eine Pipe, in die das Child schreibt
   2 => array("file", "/tmp/error-output.txt", "a") // stderr ist eine Datei,
                                                    // in die geschrieben wird
);

$cwd = '/tmp';
$env = array('some_option' => 'aeiou');

$process = proc_open('php', $descriptorspec, $pipes, $cwd, $env);

if (is_resource($process)) {
    // $pipes sieht nun so aus:
    // 0 => Schreibhandle, das auf das Child stdin verbunden ist
    // 1 => Lesehandle, das auf das Child stdout verbunden ist
    // Jedwede Fehlerausgabe wird an /tmp/error-output.txt angefügt

    fwrite($pipes[0], '<?php print_r($_ENV); ?>');
    fclose($pipes[0]);

    echo stream_get_contents($pipes[1]);
    fclose($pipes[1]);

    // Es ist wichtig, dass Sie alle Pipes schließen, bevor Sie
    // proc_close aufrufen, um Deadlocks zu vermeiden
    $return_value = proc_close($process);

    echo "Rückgabewert des Kommandos: $return_value\n";
}
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Array
(
    [some_option] => aeiou
    [PWD] => /tmp
    [SHLVL] => 1
    [_] => /usr/local/bin/php
)
Rückgabewert des Kommandos: 0
]]>
    </screen>
   </example>
  </para>

  <para>
   <example>
    <title><function>proc_open</function>-Eigenheit unter Windows</title>
    <simpara>
     Während man erwarten könnte, dass das folgende Program die Datei
     <filename>filename.txt</filename> nach dem Text <literal>suche</literal>
     durchsucht und die Ergebnisse ausgibt, verhält es sich ganz anders.
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
$descriptorspec = [STDIN, STDOUT, STDOUT];
$cmd = '"findstr" "suche" "filename.txt"';
$proc = proc_open($cmd, $descriptorspec, $pipes);
proc_close($proc);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Der Befehl "findstr" "suche" "filename.txt" ist entweder falsch geschrieben oder
konnte nicht gefunden werden.
]]>
    </screen>
    <simpara>
     Um dieses Verhalten zu vermeiden, ist es üblicherweise ausreichend das
     <parameter>command</parameter> in zusätzliche Anführungszeichen einzuschließen:
    </simpara>
    <programlisting role="php">
<![CDATA[
$cmd = '""findstr" "suche" "filename.txt""';
]]>
    </programlisting>
   </example>
  </para>

<!-- ptys are currently disabled
  <para>
   <example>
    <title>Verwendung von ptys</title>
    <programlisting role="php">
<![CDATA[
<?php
// Erstelle ein Pseudoterminal für den Child-Prozess
$descriptorspec = array(
   0 => array("pty"),
   1 => array("pty"),
   2 => array("pty")
);
$process = proc_open("cvs -d:pserver:cvsread@cvs.php.net:/repository login", $descriptorspec, $pipes);
if (is_resource($process)) {
   // Hier kann damit gearbeitet werden
}
?>
]]>
    </programlisting>
   </example>
  </para>
-->

 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Windows-Kompatibilität: Descriptoren höher 2 (stderr) sind Childprozessen
    als vererbbare Handles verfügbar, aber da die Windows-Architektur die
    Nummern der Filedescriptoren nicht mit Low-Level-Handles verbindet, hat
    der Kindprozess (bis jetzt) keine Möglichkeit, diese Handles anzusprechen.
    Stdin, stdout und stderr funktionieren wie erwartet.
   </para>
  </note>
  <note>
   <para>
    Wenn Sie nur eine unidirektionale (Einweg-) Prozesspipe benötigen, nutzen
    Sie besser <function>popen</function>, da diese Funktion leichter zu
    verwenden ist.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>popen</function></member>
    <member><function>exec</function></member>
    <member><function>system</function></member>
    <member><function>passthru</function></member>
    <member><function>stream_select</function></member>
    <member>Der <link linkend="language.operators.execution">Backtick-Operator</link></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
-->