sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Document proc_open and proc_close.

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@78004 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Wez Furlong 2002-04-13 02:00:33 +00:00
parent 97416b5093
commit 7c072d0aee
1 changed files with 129 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

130
functions/exec.xml
View file

@ -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 @@ system("touch \"/tmp/$f\"; ls -l \"/tmp/$f\""); // and here we do, so we use quo
</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>