cvs: phpdoc /en/functions exec.xml

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>