wez Fri Apr 12 22:00:33 2002 EDT
Modified files:
/phpdoc/en/functions exec.xml
Log:
Document proc_open and proc_close.
Index: phpdoc/en/functions/exec.xml
diff -u phpdoc/en/functions/exec.xml:1.27 phpdoc/en/functions/exec.xml:1.28
--- phpdoc/en/functions/exec.xml:1.27 Sat Feb 2 10:35:57 2002
+++ phpdoc/en/functions/exec.xml Fri Apr 12 22:00:33 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.27 $ -->
+<!-- $Revision: 1.28 $ -->
<reference id="ref.exec">
<title>Program Execution functions</title>
<titleabbrev>Program Execution</titleabbrev>
@@ -209,6 +209,134 @@
</para>
</refsect1>
</refentry>
+
+ <refentry id='function.proc-close'>
+ <refnamediv>
+ <refname>proc_close</refname>
+ <refpurpose>
+ Close a process opened by proc_open and return the exit code of that
+ process.
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>proc_close</methodname>
+ <methodparam><type>resource</type><parameter>process</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <function>proc_close</function> is similar to <function>popen</function>
+ except that it only works on processes opened by
+ <function>proc_open</function>.
+ <function>proc_close</function> waits for the process to terminate, and
+ returns it's exit code. If you have open pipes to that process, you
+ should <function>fclose</function> them prior to calling this function in
+ order to avoid a deadlock - the child process may not be able to exit
+ while the pipes are open.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id='function.proc-open'>
+ <refnamediv>
+ <refname>proc_open</refname>
+ <refpurpose>
+ Execute a command and open file pointers for input/output
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <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>pipes</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <function>proc_open</function> is similar to <function>popen</function>
+ but provides a much greater degree of control over the program execution.
+ <parameter>cmd</parameter> is the command to be executed by the shell.
+ <parameter>descriptorspec</parameter> is an indexed array where the
+ key represents the descriptor number and the value represents how PHP
+ will pass that descriptor to the child process.
+ <parameter>pipes</parameter> will be set to an indexed array of file
+ pointers that correspond to PHP's end of any pipes that are created.
+ The return value is a resource representing the process; you should
+ free it using <function>proc_close</function> when you are finished
+ with it.
+ </para>
+ <para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+$descriptorspec = array(
+ 0 => array("pipe", "r"), // stdin is a pipe that the child will read from
+ 1 => array("pipe", "w"), // stdout is a pipe that the child will write to
+ 2 => array("file", "/tmp/error-output.txt", "a"), // stderr is a file to write to
+);
+$process = proc_open("php", $descriptorspec, $pipes);
+if (is_resource($process)) {
+ // $pipes now looks like this:
+ // 0 => writeable handle connected to child stdin
+ // 1 => readable handle connected to child stdout
+ // Any error output will be appended to /tmp/error-output.txt
+
+ fwrite($pipes[0], "<?php echo \"Hello World!\"; ?>");
+
+ while(!feof($pipes[1])) {
+ echo fgets($pipes[1], 1024);
+ }
+
+ $return_value = proc_close($process);
+
+ echo "command returned $return_value\n";
+}
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
+ <para>
+ The file descriptor numbers in <parameter>descriptorspec</parameter> are
+ not limited to 0, 1 and 2 - you may specify any valid file descriptor
+ number and it will be passed to the child process. This allows your
+ script to interoperate with other scripts that run as "co-processes".
+ In particular, this is useful for passing passphrases to programs like
+ PGP, GPG and openssl in a more secure manner. It is also useful for
+ reading status information provided by those programs on auxillary
+ file descriptors.
+ </para>
+ <note>
+ <para>
+ Windows compatibility: Descriptors beyond 2 (stderr) are made
+ available to the child process as inheritable handles, but since
+ the Windows architecture does not associate file descriptor numbers
+ with low-level handles, the child process does not (yet) have a means
+ of accessing those handles. Stdin, stdout and stderr work as expected.
+ </para>
+ </note>
+ <note>
+ <para>
+ This function was introduced in PHP 4.3.0.
+ </para>
+ </note>
+ <note>
+ <para>
+ If you only need a uni-directional (one-way) process pipe, use
+ <function>popen</function> instead, as it is much easier to use.
+ </para>
+ </note>
+
+ <para>
+ See also <function>exec</function>, <function>system</function>,
+ <function>passthru</function>, <function>popen</function>,
+ <function>escapeshellcmd</function>, and the <link
+ linkend="language.operators.execution">backtick operator</link>.
+ </para>
+
+ </refsect1>
+ </refentry>
+
+
<refentry id="function.system">
<refnamediv>
