mirror of
https://github.com/php/doc-de.git
synced 2026-03-24 07:12:15 +01:00
444 lines
15 KiB
XML
444 lines
15 KiB
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
|
|
-->
|