<!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>Opens process file pointer</title> </head> <body><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="function.pclose.html">pclose</a></div> <div class="next" style="text-align: right; float: right;"><a href="function.readfile.html">readfile</a></div> <div class="up"><a href="ref.filesystem.html">Filesystem Functions</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div><hr /><div id="function.popen" class="refentry"> <div class="refnamediv"> <h1 class="refname">popen</h1> <p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">popen</span> — <span class="dc-title">Opens process file pointer</span></p> </div> <div class="refsect1 description" id="refsect1-function.popen-description"> <h3 class="title">Description</h3> <div class="methodsynopsis dc-description"> <span class="type">resource</span> <span class="methodname"><strong>popen</strong></span> ( <span class="methodparam"><span class="type">string</span> <code class="parameter">$command</code></span> , <span class="methodparam"><span class="type">string</span> <code class="parameter">$mode</code></span> )</div> <p class="para rdfs-comment"> Opens a pipe to a process executed by forking the command given by command. </p> </div> <div class="refsect1 parameters" id="refsect1-function.popen-parameters"> <h3 class="title">Parameters</h3> <p class="para"> <dl> <dt> <span class="term"><em><code class="parameter">command</code></em></span> <dd> <p class="para"> The command </p> </dd> </dt> <dt> <span class="term"><em><code class="parameter">mode</code></em></span> <dd> <p class="para"> The mode </p> </dd> </dt> </dl> </p> </div> <div class="refsect1 returnvalues" id="refsect1-function.popen-returnvalues"> <h3 class="title">Return Values</h3> <p class="para"> Returns a file pointer identical to that returned by <span class="function"><a href="function.fopen.html" class="function">fopen()</a></span>, except that it is unidirectional (may only be used for reading or writing) and must be closed with <span class="function"><a href="function.pclose.html" class="function">pclose()</a></span>. This pointer may be used with <span class="function"><a href="function.fgets.html" class="function">fgets()</a></span>, <span class="function"><a href="function.fgetss.html" class="function">fgetss()</a></span>, and <span class="function"><a href="function.fwrite.html" class="function">fwrite()</a></span>. When the mode is 'r', the returned file pointer equals to the STDOUT of the command, when the mode is 'w', the returned file pointer equals to the STDIN of the command. </p> <p class="para"> If an error occurs, returns <strong><code>FALSE</code></strong>. </p> </div> <div class="refsect1 examples" id="refsect1-function.popen-examples"> <h3 class="title">Examples</h3> <p class="para"> <div class="example" id="example-2420"> <p><strong>Example #1 <span class="function"><strong>popen()</strong></span> example</strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br />$handle </span><span style="color: #007700">= </span><span style="color: #0000BB">popen</span><span style="color: #007700">(</span><span style="color: #DD0000">"/bin/ls"</span><span style="color: #007700">, </span><span style="color: #DD0000">"r"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> </div> </p> <p class="para"> If the command to be executed could not be found, a valid resource is returned. This may seem odd, but makes sense; it allows you to access any error message returned by the shell: <div class="example" id="example-2421"> <p><strong>Example #2 <span class="function"><strong>popen()</strong></span> example</strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br />error_reporting</span><span style="color: #007700">(</span><span style="color: #0000BB">E_ALL</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* Add redirection so we can get stderr. */<br /></span><span style="color: #0000BB">$handle </span><span style="color: #007700">= </span><span style="color: #0000BB">popen</span><span style="color: #007700">(</span><span style="color: #DD0000">'/path/to/executable 2>&1'</span><span style="color: #007700">, </span><span style="color: #DD0000">'r'</span><span style="color: #007700">);<br />echo </span><span style="color: #DD0000">"'</span><span style="color: #0000BB">$handle</span><span style="color: #DD0000">'; " </span><span style="color: #007700">. </span><span style="color: #0000BB">gettype</span><span style="color: #007700">(</span><span style="color: #0000BB">$handle</span><span style="color: #007700">) . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$read </span><span style="color: #007700">= </span><span style="color: #0000BB">fread</span><span style="color: #007700">(</span><span style="color: #0000BB">$handle</span><span style="color: #007700">, </span><span style="color: #0000BB">2096</span><span style="color: #007700">);<br />echo </span><span style="color: #0000BB">$read</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">pclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$handle</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> </div> </p> </div> <div class="refsect1 notes" id="refsect1-function.popen-notes"> <h3 class="title">Notes</h3> <blockquote class="note"><p><strong class="note">Note</strong>: <p class="para"> If you're looking for bi-directional support (two-way), use <span class="function"><a href="function.proc-open.html" class="function">proc_open()</a></span>. </p> </p></blockquote> <blockquote class="note"><p><strong class="note">Note</strong>: <span class="simpara">When <a href="features.safe-mode.html" class="link">safe mode</a> is enabled, you can only execute files within the <a href="ini.sect.safe-mode.html#ini.safe-mode-exec-dir" class="link">safe_mode_exec_dir</a>. For practical reasons, it is currently not allowed to have <em>..</em> components in the path to the executable.</span></p></blockquote> <div class="warning"><strong class="warning">Warning</strong><p class="simpara">With <a href="features.safe-mode.html" class="link">safe mode</a> enabled, the command string is escaped with <span class="function"><a href="function.escapeshellcmd.html" class="function">escapeshellcmd()</a></span>. Thus, <em>echo y | echo x</em> becomes <em>echo y \| echo x</em>.</p></div> </div> <div class="refsect1 seealso" id="refsect1-function.popen-seealso"> <h3 class="title">See Also</h3> <p class="para"> <ul class="simplelist"> <li class="member"> <span class="function"><a href="function.pclose.html" class="function" rel="rdfs-seeAlso">pclose()</a> - Closes process file pointer</span></li> <li class="member"> <span class="function"><a href="function.fopen.html" class="function" rel="rdfs-seeAlso">fopen()</a> - Opens file or URL</span></li> <li class="member"> <span class="function"><a href="function.proc-open.html" class="function" rel="rdfs-seeAlso">proc_open()</a> - Execute a command and open file pointers for input/output</span></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.pclose.html">pclose</a></div> <div class="next" style="text-align: right; float: right;"><a href="function.readfile.html">readfile</a></div> <div class="up"><a href="ref.filesystem.html">Filesystem Functions</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div></body></html>