<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297626 $ -->
<!-- splitted from ./en/functions/exec.xml, last change in rev 1.28 -->
  <refentry xml:id='function.proc-open' xmlns="http://docbook.org/ns/docbook">
   <refnamediv>
    <refname>proc_open</refname>
    <refpurpose>
     Execute a command and open file pointers for input/output
    </refpurpose>
   </refnamediv>
   <refsect1 role="description">
    &reftitle.description;
     <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 role="reference">pipes</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>cwd</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>env</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>other_options</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.
    </para>

<!-- ptys are currently disabled in the sources
    <para>
     PHP 5 introduces pty support for systems with Unix98 ptys. This allows
     your script to interact with applications that expect to be talking to a
     terminal.  A pty works like a pipe, but is bi-directional, so there is no
     need to specify a read/write mode.  The example below shows how to use a
     pty; note that you don't have to have all descriptors talking to a pty.
     Also note that only one pty is created, even though pty is specified 3
     times.  In a future version of PHP, it might be possible to do more than
     just read and write to the pty.
    </para>
-->

   </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>cmd</parameter></term>
     <listitem>
      <para>
       The command to execute
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>descriptorspec</parameter></term>
     <listitem>
      <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.
      </para>
      <para>
       Each element can be:
       <simplelist>
        <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 <literal>pipe</literal> (the second
         element is either <literal>r</literal> to pass the read end of the pipe
         to the process, or <literal>w</literal> to pass the write end) and
         <literal>file</literal> (the second element is a filename).
        </member>
        <member>
         A stream resource representing a real file descriptor (e.g. opened file,
         a socket, <constant>STDIN</constant>).
        </member>
       </simplelist>
      </para>
      <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.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>pipes</parameter></term>
     <listitem>
      <para>
       Will be set to an indexed array of file pointers that correspond to
       PHP's end of any pipes that are created.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>cwd</parameter></term>
     <listitem>
      <para>
       The initial working dir for the command. This must be an
       <emphasis role="strong">absolute</emphasis> directory path, or &null;
       if you want to use the default value (the working dir of the current
       PHP process)
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>env</parameter></term>
     <listitem>
      <para>
       An array with the environment variables for the command that will be
       run, or &null; to use the same environment as the current PHP process
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>other_options</parameter></term>
     <listitem>
      <para>
       Allows you to specify additional options. Currently supported options
       include:
       <simplelist>
        <member>
         <literal>suppress_errors</literal> (windows only): suppresses errors
         generated by this function when it's set to &true;
        </member>
        <member>
         <literal>bypass_shell</literal> (windows only): bypass
         <literal>cmd.exe</literal> shell when set to &true;
        </member>
        <member>
         <literal>context</literal>: stream context used when opening files
         (created with <function>stream_context_create</function>)
        </member>
        <member>
         <literal>binary_pipes</literal>: open pipes in binary mode, instead
         of using the usual <literal>stream_encoding</literal>
        </member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a resource representing the process, which should be freed using
   <function>proc_close</function> when you are finished with it. On failure
   returns &false;.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <!-- FIXME PHP_6
      <row>
       <entry>6.0.0</entry>
       <entry>
        Added the <literal>context</literal> and
        <literal>binary_pipes</literal> options to the
        <parameter>other_options</parameter> parameter.
       </entry>
      </row>
      -->
      <row>
       <entry>5.2.1</entry>
       <entry>
        Added the <literal>bypass_shell</literal> option to the
        <parameter>other_options</parameter> parameter.
       </entry>
      </row>
      <row>
       <entry>5.0.0</entry>
       <entry>
        Added the <parameter>cwd</parameter>, <parameter>env</parameter> and
        <parameter>other_options</parameter> parameters.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>A <function>proc_open</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$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
);

$cwd = '/tmp';
$env = array('some_option' => 'aeiou');

$process = proc_open('php', $descriptorspec, $pipes, $cwd, $env);

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 print_r($_ENV); ?>');
    fclose($pipes[0]);

    echo stream_get_contents($pipes[1]);
    fclose($pipes[1]);

    // It is important that you close any pipes before calling
    // proc_close in order to avoid a deadlock
    $return_value = proc_close($process);

    echo "command returned $return_value\n";
}
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Array
(
    [some_option] => aeiou
    [PWD] => /tmp
    [SHLVL] => 1
    [_] => /usr/local/bin/php
)
command returned 0
]]>
    </screen>
   </example>
  </para>

<!-- ptys are currently disabled
  <para>
   <example>
    <title>ptys usage</title>
    <programlisting role="php">
<![CDATA[
<?php
// Create a pseudo terminal for the child process
$descriptorspec = array(
   0 => array("pty"),
   1 => array("pty"),
   2 => array("pty")
);
$process = proc_open("cvs -d:pserver:cvsread@cvs.php.net:/repository login", $descriptorspec, $pipes);
if (is_resource($process)) {
   // work with it here
}
?>
]]>
    </programlisting>
   </example>
  </para>
-->

 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <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>
   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>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>popen</function></member>
    <member><function>exec</function></member>
    <member><function>system</function></member>
    <member><function>passthru</function></member>
    <member><function>stream_select</function></member>
    <member>The <link linkend="language.operators.execution">backtick operator</link></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->