proc-open.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e41aab5ecacf449e51179886c17f1d41735b0234  Maintainer: chuso Status: ready -->
<!-- Reviewed: no -->
<!-- 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>
   Ejecuta un comando y abre un puntero de fichero para entrada/salida
  </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> es similar a <function>popen</function>
   pero provee un grado de control mucho más grande sobre la ejecución del programa.
  </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>
       El comando a ejecutar
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>descriptorspec</parameter></term>
     <listitem>
      <para>
       Un array indexado donde la clave representa el número descriptor y el valor
       representa como PHP pasará que descriptor para que proceso hijo. 0 es stdin,
       1 es stdout, 2 es stderr.
      </para>
      <para>
       Cada elemento puede ser:
       <simplelist>
        <member>Un array que describe la tubería que se va a pasar al proceso. El primer
         elemento es el tipo de descriptor, y el segundo elemento es una opción para
         el tipo dado. Los tipos válidos son: <literal>pipe</literal> (en este caso el segundo
         elemento sería <literal>r</literal> para pasar a leer el final de la tubería
         para el proceso, o <literal>w</literal> para pasar a escribir al final) y
         <literal>file</literal> (en este caso el segundo elemento sería el nombre de fichero).
        </member>
        <member>
         Un recurso de flujo representando un descriptor de un fichero real (p.e. un
         fichero abierto, un socket, <constant>STDIN</constant>).
        </member>
       </simplelist>
      </para>
      <para>
       Los números descriptores de fichero no estan limitados a 0, 1 y 2. Se puede
       especificar cualquier número descriptor válido de fichero, y este ser pasado
       al proceso hijo. Esto permite a su script para inteoperar con otros
       scripts que corren como "co-procesos". En particular esto es útil
       pasando passphrases para programas como PGP, GPG y OpenSSL de una manera más
       segura. Esto es útil también para la lectura de la información
       del estado provista por estos programas en descriptores de fichero auxiliares.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>pipes</parameter></term>
     <listitem>
      <para>
       En un array indexado es establecerán los punteros de fichero que se corresponden con el fin de cualquier tuberia
       PHP que se haya creado.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>cwd</parameter></term>
     <listitem>
      <para>
       El directorio inicial de trabajo para el comando. Este debe
       ser una ruta <emphasis role="strong">absoluta</emphasis>, o si se prefiere puede ser &null;
       si se desea usar el valor por defecto (entonces será el directorio de trabajo del proceso
       PHP en curso)
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>env</parameter></term>
     <listitem>
      <para>
       Un array con las variables de entorno para el comando que será
       ejecutado, o &null; para usar el mismo entorno como el del proceso PHP en curso.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>other_options</parameter></term>
     <listitem>
      <para>
       Permite especificar opciones adicionales. Actualmente las opciones soportadas
       incluidas son:
       <simplelist>
        <member>
         <literal>suppress_errors</literal> (solo windows): suprime errores
         generados por esta función cuando es establece en &true;
        </member>
        <member>
         <literal>bypass_shell</literal> (solo windows): Desvia
         en la consola de <literal>cmd.exe</literal> cuando se establece en &true;
        </member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve un recurso representando el proceso, cuando se haya terminado con él,
   deberá ser liberado usando<function>proc_close</function>. En caso de error
   devuelve &false;.
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>5.2.1</entry>
       <entry>
        Añadida la opción <literal>bypass_shell</literal>
        al parámetro <parameter>other_options</parameter>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo de <function>proc_open</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$descriptorspec = array(
   0 => array("pipe", "r"),  // stdin es una tubería usada por el hijo para lectura
   1 => array("pipe", "w"),  // stdout es una tubería usada por el hijo para escritura
   2 => array("file", "/tmp/error-output.txt", "a") // stderr es un fichero para escritura
);

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

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

if (is_resource($process)) {
    // $pipes ahora será algo como:
    // 0 => gestor de escritura conectado al stdin hijo
    // 1 => gestor de lectura conectado al stdout hijo
    // Cualquier error de salida será anexado a /tmp/error-output.txt

    fwrite($pipes[0], '<?php print_r($_ENV); ?>');
    fclose($pipes[0]);

    echo "--".stream_get_contents($pipes[1])."--";
    fclose($pipes[1]);

    // Es importante que se cierren todas las tubería antes de llamar a
    // proc_close para evitar así un punto muerto
    $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
// Crear un pseudo terminal para el proceso hijo
$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)) {
   // el trabajo con él iria aquí
}
?>
]]>
    </programlisting>
   </example>
  </para>
-->
  
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Compatibilidad con Windows: Los descriptores por encima de 2 (stderr) se ponen a disposición
    del proceso hijo como gestores heredables, pero desde la arquitectura de Windows
    no se asocia el número descriptor de fichero con los gestores de bajo nivel.
    El proceso hijo (todavia) no tiene un medio de acceso a estos gestores.
    Stdin, stdout and stderr funcionan como se esperaba.
   </para>
  </note>
  <note>
   <para>
    Si solamente se necesita una tubería de proceso unidireccional, es mejor usar
    <function>popen</function> en su lugar, ya que es mucho más fácil de utilizar.
   </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
-->