Source of: /manual/en/function.proc-open.php
<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/ref.exec.inc";
$setup = array (
'home' =>
array (
0 => 'index.php',
1 => 'PHP Manual',
),
'head' =>
array (
0 => 'UTF-8',
1 => 'en',
),
'this' =>
array (
0 => 'function.proc-open.php',
1 => 'proc_open',
),
'up' =>
array (
0 => 'ref.exec.php',
1 => 'Program execution Functions',
),
'prev' =>
array (
0 => 'function.proc-nice.php',
1 => 'proc_nice',
),
'next' =>
array (
0 => 'function.proc-terminate.php',
1 => 'proc_terminate',
),
);
$setup["toc"] = $TOC;
$setup["parents"] = $PARENTS;
manual_setup($setup);
manual_header();
?>
<div id="function.proc-open" class="refentry">
<div class="refnamediv">
<h1 class="refname">proc_open</h1>
<p class="verinfo">(PHP 4 >= 4.3.0, PHP 5)</p><p class="refpurpose"><span class="refname">proc_open</span> — <span class="dc-title">
Execute a command and open file pointers for input/output
</span></p>
</div>
<a name="function.proc-open.description"></a><div class="refsect1 description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">resource</span> <span class="methodname"><b>proc_open</b></span>
( <span class="methodparam"><span class="type">string</span> <tt class="parameter">$cmd</tt></span>
, <span class="methodparam"><span class="type">array</span> <tt class="parameter">$descriptorspec</tt></span>
, <span class="methodparam"><span class="type">array</span> <tt class="parameter reference">&$pipes</tt></span>
[, <span class="methodparam"><span class="type">string</span> <tt class="parameter">$cwd</tt></span>
[, <span class="methodparam"><span class="type">array</span> <tt class="parameter">$env</tt></span>
[, <span class="methodparam"><span class="type">array</span> <tt class="parameter">$other_options</tt></span>
]]] )</div>
<p class="para rdfs-comment">
<b>proc_open()</b> is similar to <a href="function.popen.php" class="function">popen()</a>
but provides a much greater degree of control over the program execution.
</p>
</div>
<a name="function.proc-open.parameters"></a><div class="refsect1 parameters">
<h3 class="title">Parameters</h3>
<p class="para">
</p><dl>
<dt class="varlistentry">
<span class="term"><i><tt class="parameter">cmd</tt></i>
</span>
</dt><dd class="listitem">
<p class="para">
The command to execute
</p>
</dd>
<dt class="varlistentry">
<span class="term"><i><tt class="parameter">descriptorspec</tt></i>
</span>
</dt><dd class="listitem">
<p class="para">
An indexed array where the key represents the descriptor number and the
value represents how PHP will pass that descriptor to the child
process. 0 is stdin, 1 is stdout, while 2 is stderr.
</p>
<p class="para">
Each element can be:
</p><ul class="simplelist">
<li class="member">An array describing the pipe to pass to the process. The first
element is the descriptor type and the second element is an option for
the given type. Valid types are <i>pipe</i> (the second
element is either <i>r</i> to pass the read end of the pipe
to the process, or <i>w</i> to pass the write end) and
<i>file</i> (the second element is a filename).
</li>
<li class="member">
A stream resource representing a real file descriptor (e.g. opened file,
a socket, <b><tt class="constant">STDIN</tt></b>).
</li>
</ul><p>
</p>
<p class="para">
The file descriptor numbers 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 auxiliary file descriptors.
</p>
</dd>
<dt class="varlistentry">
<span class="term"><i><tt class="parameter">pipes</tt></i>
</span>
</dt><dd class="listitem">
<p class="para">
Will be set to an indexed array of file pointers that correspond to
PHP's end of any pipes that are created.
</p>
</dd>
<dt class="varlistentry">
<span class="term"><i><tt class="parameter">cwd</tt></i>
</span>
</dt><dd class="listitem">
<p class="para">
The initial working dir for the command. This must be an
<em class="emphasis">absolute</em> directory path, or <b><tt class="constant">NULL</tt></b>
if you want to use the default value (the working dir of the current
PHP process)
</p>
</dd>
<dt class="varlistentry">
<span class="term"><i><tt class="parameter">env</tt></i>
</span>
</dt><dd class="listitem">
<p class="para">
An array with the environment variables for the command that will be
run, or <b><tt class="constant">NULL</tt></b> to use the same environment as the current PHP process
</p>
</dd>
<dt class="varlistentry">
<span class="term"><i><tt class="parameter">other_options</tt></i>
</span>
</dt><dd class="listitem">
<p class="para">
Allows you to specify additional options. Currently supported options
include:
</p><ul class="simplelist">
<li class="member">
<i>suppress_errors</i> (windows only): suppresses errors
generated by this function when it's set to <b><tt class="constant">TRUE</tt></b>
</li>
<li class="member">
<i>bypass_shell</i> (windows only): bypass
<i>cmd.exe</i> shell when set to <b><tt class="constant">TRUE</tt></b>
</li>
<li class="member">
<i>context</i>: stream context used when opening files
(created with <a href="function.stream-context-create.php" class="function">stream_context_create()</a>)
</li>
<li class="member">
<i>binary_pipes</i>: open pipes in binary mode, instead
of using the usual <i>stream_encoding</i>
</li>
</ul><p>
</p>
</dd>
</dl>
<p>
</p>
</div>
<a name="function.proc-open.returnvalues"></a><div class="refsect1 returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns a resource representing the process, which should be freed using
<a href="function.proc-close.php" class="function">proc_close()</a> when you are finished with it. On failure
returns <b><tt class="constant">FALSE</tt></b>.
</p>
</div>
<a name="function.proc-open.changelog"></a><div class="refsect1 changelog">
<h3 class="title">Changelog</h3>
<p class="para">
</p><table class="doctable informaltable">
<thead valign="middle">
<tr valign="middle">
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody valign="middle" class="tbody">
<tr valign="middle">
<td align="left">6.0.0</td>
<td align="left">
Added the <i>context</i> and
<i>binary_pipes</i> options to the
<i><tt class="parameter">other_options</tt></i>
parameter.
</td>
</tr>
<tr valign="middle">
<td align="left">5.2.1</td>
<td align="left">
Added the <i>bypass_shell</i> option to the
<i><tt class="parameter">other_options</tt></i>
parameter.
</td>
</tr>
<tr valign="middle">
<td align="left">5.0.0</td>
<td align="left">
Added the <i><tt class="parameter">cwd</tt></i>
, <i><tt class="parameter">env</tt></i>
and
<i><tt class="parameter">other_options</tt></i>
parameters.
</td>
</tr>
</tbody>
</table>
<p>
</p>
</div>
<a name="function.proc-open.examples"></a><div class="refsect1 examples">
<h3 class="title">Examples</h3>
<p class="para">
</p><div class="example">
<p><b>Example #1 A <b>proc_open()</b> example</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$descriptorspec </span><span style="color: #007700">= array(<br /> </span><span style="color: #0000BB">0 </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">"pipe"</span><span style="color: #007700">, </span><span style="color: #DD0000">"r"</span><span style="color: #007700">), </span><span style="color: #FF8000">// stdin is a pipe that the child will read from<br /> </span><span style="color: #0000BB">1 </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">"pipe"</span><span style="color: #007700">, </span><span style="color: #DD0000">"w"</span><span style="color: #007700">), </span><span style="color: #FF8000">// stdout is a pipe that the child will write to<br /> </span><span style="color: #0000BB">2 </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">"file"</span><span style="color: #007700">, </span><span style="color: #DD0000">"/tmp/error-output.txt"</span><span style="color: #007700">, </span><span style="color: #DD0000">"a"</span><span style="color: #007700">) </span><span style="color: #FF8000">// stderr is a file to write to<br /></span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$cwd </span><span style="color: #007700">= </span><span style="color: #DD0000">'/tmp'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$env </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'some_option' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'aeiou'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$process </span><span style="color: #007700">= </span><span style="color: #0000BB">proc_open</span><span style="color: #007700">(</span><span style="color: #DD0000">'php'</span><span style="color: #007700">, </span><span style="color: #0000BB">$descriptorspec</span><span style="color: #007700">, </span><span style="color: #0000BB">$pipes</span><span style="color: #007700">, </span><span style="color: #0000BB">$cwd</span><span style="color: #007700">, </span><span style="color: #0000BB">$env</span><span style="color: #007700">);<br /><br />if (</span><span style="color: #0000BB">is_resource</span><span style="color: #007700">(</span><span style="color: #0000BB">$process</span><span style="color: #007700">)) {<br /> </span><span style="color: #FF8000">// $pipes now looks like this:<br /> // 0 => writeable handle connected to child stdin<br /> // 1 => readable handle connected to child stdout<br /> // Any error output will be appended to /tmp/error-output.txt<br /><br /> </span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$pipes</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">], </span><span style="color: #DD0000">'<?php print_r($_ENV); ?>'</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$pipes</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]);<br /><br /> echo </span><span style="color: #0000BB">stream_get_contents</span><span style="color: #007700">(</span><span style="color: #0000BB">$pipes</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]);<br /> </span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$pipes</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]);<br /><br /> </span><span style="color: #FF8000">// It is important that you close any pipes before calling<br /> // proc_close in order to avoid a deadlock<br /> </span><span style="color: #0000BB">$return_value </span><span style="color: #007700">= </span><span style="color: #0000BB">proc_close</span><span style="color: #007700">(</span><span style="color: #0000BB">$process</span><span style="color: #007700">);<br /><br /> echo </span><span style="color: #DD0000">"command returned </span><span style="color: #0000BB">$return_value</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents para"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Array
(
[some_option] => aeiou
[PWD] => /tmp
[SHLVL] => 1
[_] => /usr/local/bin/php
)
command returned 0
</pre></div>
</div>
</div><p>
</p>
</div>
<a name="function.proc-open.notes"></a><div class="refsect1 notes">
<h3 class="title">Notes</h3>
<blockquote><p><b class="note">Note</b>:
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.
<br />
</p></blockquote>
<blockquote><p><b class="note">Note</b>:
If you only need a uni-directional (one-way) process pipe, use
<a href="function.popen.php" class="function">popen()</a> instead, as it is much easier to use.
<br />
</p></blockquote>
</div>
<a name="function.proc-open.seealso"></a><div class="refsect1 seealso">
<h3 class="title">See Also</h3>
<p class="para">
</p><ul class="simplelist">
<li class="member"><a href="function.popen.php" class="function" rel="rdfs-seeAlso">popen()</a> - Opens process file pointer</li>
<li class="member"><a href="function.exec.php" class="function" rel="rdfs-seeAlso">exec()</a> - Execute an external program</li>
<li class="member"><a href="function.system.php" class="function" rel="rdfs-seeAlso">system()</a> - Execute an external program and display the output</li>
<li class="member"><a href="function.passthru.php" class="function" rel="rdfs-seeAlso">passthru()</a> - Execute an external program and display raw output</li>
<li class="member"><a href="function.stream-select.php" class="function" rel="rdfs-seeAlso">stream_select()</a> - Runs the equivalent of the select() system call on the given
arrays of streams with a timeout specified by tv_sec and tv_usec</li>
<li class="member">The <a href="language.operators.execution.php" class="link">backtick operator</a></li>
</ul><p>
</p>
</div>
</div><?php manual_footer(); ?>
