<!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>