archived-doc-de/reference/exec/functions/proc-open.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: sammywg Status: ready -->
<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>resource</type><methodname>proc_open</methodname>
    <methodparam><type>string</type><parameter>cmd</parameter></methodparam>
    <methodparam><type>array</type><parameter>descriptorspec</parameter></methodparam>
    <methodparam><type>array</type><parameter role="reference">pipes</parameter></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>cwd</parameter></methodparam>
    <methodparam choice="opt"><type>array</type><parameter>env</parameter></methodparam>
    <methodparam choice="opt"><type>array</type><parameter>other_options</parameter></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 PTY-Support für Systeme mit Unix98-PTYs ein. Dies erlaubt es
   Ihren Skripten, mit Applikationen zu interagieren, die mit einem Terminal
   zu kommunizieren erwarten. Ein PTY arbeitet wie eine Pipe, ist aber
   bidirektional, daher müssen Sie keinen Lese-/Schreibmodus angeben. Das
   folgende Beispiel zeigt, wie ein PTY verwendet wird. Beachten Sie, dass
   nicht alle Filedescriptoren mit dem PTY verbunden sein müssen.
   Beachten Sie außerdem, 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>cmd</parameter></term>
     <listitem>
      <para>
       Das auszuführende Kommando.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>descriptorspec</parameter></term>
     <listitem>
      <para>
       Ein indexiertes Array, in dem die Schlüssel die Descriptornummer und die
       Werte die Art und Weise repräsentieren, 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).
        </member>
        <member>
         Eine Streamressource, die einen echten Filedescriptor repräsentiert
         (z.B. 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 an Programme wie PGP, GPG und openssl auf
       sichere Art ü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</parameter></term>
     <listitem>
      <para>
       Ein Array mit den Umgebungsvariablen für das auszuführende Kommando, oder
       &null;, wenn Sie das gleiche Environment wie der aktuelle PHP-Prozess
       nutzen wollen.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>other_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>context</literal>: Streamcontext, der beim Öffnen von Dateien
         verwendet wird (erstellt mit <function>stream_context_create</function>.
        </member>
        <member>
         <literal>binary_pipes</literal>: Öffnet Pipes im Binärmodus anstatt
         das übliche <literal>stream_encoding</literal> zu verwenden.
        </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="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>6.0.0</entry>
       <entry>
        Die Optionen <literal>context</literal> und
        <literal>binary_pipes</literal> wurden dem
        <parameter>other_options</parameter> hinzugefügt.
       </entry>
      </row>
      <row>
       <entry>5.2.1</entry>
       <entry>
        Die Option <literal>bypass_shell</literal> wurde dem Parameter
        <parameter>other_options</parameter> hinzugefügt.
       </entry>
      </row>
      <row>
       <entry>5.0.0</entry>
       <entry>
        Die Parameter <parameter>cwd</parameter>, <parameter>env</parameter>
        und <parameter>other_options</parameter> wurden 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 Fehlerausgaben werden 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>

<!-- 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
-->