<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Execute a command and open file pointers for input/output</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.proc-nice.html">proc_nice</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.proc-terminate.html">proc_terminate</a></div>
<div class="up"><a href="ref.exec.html">Program execution Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><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>
<div class="refsect1 description" id="refsect1-function.proc-open-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">resource</span> <span class="methodname"><strong>proc_open</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$cmd</code></span>
, <span class="methodparam"><span class="type">array</span> <code class="parameter">$descriptorspec</code></span>
, <span class="methodparam"><span class="type">array</span> <code class="parameter reference">&$pipes</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$cwd</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$env</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$other_options</code></span>
]]] )</div>
<p class="para rdfs-comment">
<span class="function"><strong>proc_open()</strong></span> is similar to <span class="function"><a href="function.popen.html" class="function">popen()</a></span>
but provides a much greater degree of control over the program execution.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.proc-open-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">cmd</code></em></span>
<dd>
<p class="para">
The command to execute
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">descriptorspec</code></em></span>
<dd>
<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:
<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 <em>pipe</em> (the second
element is either <em>r</em> to pass the read end of the pipe
to the process, or <em>w</em> to pass the write end) and
<em>file</em> (the second element is a filename).
</li>
<li class="member">
A stream resource representing a real file descriptor (e.g. opened file,
a socket, <strong><code>STDIN</code></strong>).
</li>
</ul>
</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>
<dt>
<span class="term"><em><code class="parameter">pipes</code></em></span>
<dd>
<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>
<dt>
<span class="term"><em><code class="parameter">cwd</code></em></span>
<dd>
<p class="para">
The initial working dir for the command. This must be an
<em class="emphasis">absolute</em> directory path, or <strong><code>NULL</code></strong>
if you want to use the default value (the working dir of the current
PHP process)
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">env</code></em></span>
<dd>
<p class="para">
An array with the environment variables for the command that will be
run, or <strong><code>NULL</code></strong> to use the same environment as the current PHP process
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">other_options</code></em></span>
<dd>
<p class="para">
Allows you to specify additional options. Currently supported options
include:
<ul class="simplelist">
<li class="member">
<em>suppress_errors</em> (windows only): suppresses errors
generated by this function when it's set to <strong><code>TRUE</code></strong>
</li>
<li class="member">
<em>bypass_shell</em> (windows only): bypass
<em>cmd.exe</em> shell when set to <strong><code>TRUE</code></strong>
</li>
</ul>
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.proc-open-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns a resource representing the process, which should be freed using
<span class="function"><a href="function.proc-close.html" class="function">proc_close()</a></span> when you are finished with it. On failure
returns <strong><code>FALSE</code></strong>.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.proc-open-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>5.2.1</td>
<td>
Added the <em>bypass_shell</em> option to the
<em><code class="parameter">other_options</code></em> parameter.
</td>
</tr>
<tr>
<td>5.0.0</td>
<td>
Added the <em><code class="parameter">cwd</code></em>, <em><code class="parameter">env</code></em> and
<em><code class="parameter">other_options</code></em> parameters.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.proc-open-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-3677">
<p><strong>Example #1 A <span class="function"><strong>proc_open()</strong></span> example</strong></p>
<div class="example-contents">
<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"><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>
</div>
<div class="refsect1 notes" id="refsect1-function.proc-open-notes">
<h3 class="title">Notes</h3>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="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.
</p>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If you only need a uni-directional (one-way) process pipe, use
<span class="function"><a href="function.popen.html" class="function">popen()</a></span> instead, as it is much easier to use.
</p>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-function.proc-open-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.popen.html" class="function" rel="rdfs-seeAlso">popen()</a> - Opens process file pointer</span></li>
<li class="member"> <span class="function"><a href="function.exec.html" class="function" rel="rdfs-seeAlso">exec()</a> - Execute an external program</span></li>
<li class="member"> <span class="function"><a href="function.system.html" class="function" rel="rdfs-seeAlso">system()</a> - Execute an external program and display the output</span></li>
<li class="member"> <span class="function"><a href="function.passthru.html" class="function" rel="rdfs-seeAlso">passthru()</a> - Execute an external program and display raw output</span></li>
<li class="member"> <span class="function"><a href="function.stream-select.html" 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</span></li>
<li class="member">The <a href="language.operators.execution.html" class="link">backtick operator</a></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.proc-nice.html">proc_nice</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.proc-terminate.html">proc_terminate</a></div>
<div class="up"><a href="ref.exec.html">Program execution Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
