doc-fr/reference/exec/functions/proc-open.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0b4c5897dd4f9ca3ec78ac7e1be64ffe82b27d32 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id='function.proc-open' xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>proc_open</refname>
  <refpurpose>
   Exécute une commande et ouvre les pointeurs de fichiers pour les entrées / sorties
  </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> est similaire à <function>popen</function>
   mais fournit un plus grand degré de contrôle sur l'exécution du programme.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>cmd</parameter></term>
     <listitem>
      <para>
       La commande à exécuter
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>descriptorspec</parameter></term>
     <listitem>
      <para>
       Un tableau indexé, dont les clés représentent le numéro de descripteur 
       et la valeur la méthode avec laquelle PHP va passer ce descripteur au 
       processus fils. 0 est stdin, 1 est stdout, et 2 est stderr.
      </para>
      <para>
       Chaque élément peut être :
       <simplelist>
        <member>
         Un tableau décrivant le pipe à passer au processus. Le premier élément
         est le type du descripteur et le second est une option pour le type donné.
         Les types valides sont <literal>pipe</literal> (le second élément est soit
         <literal>r</literal> pour passer la fin de lecture du pipe au processus, ou
         <literal>w</literal> pour passer la fin d'écriture) et
         <literal>file</literal> (le second élément est le nom de fichier).
        </member>
        <member>
         Une ressource de flux représentant un descripteur de fichier (e.g. un fichier
         ouvert, un socket, ou bien <constant>STDIN</constant>).
        </member>
       </simplelist>
      </para>
      <para>
       Les numéros de pointeurs de fichiers ne sont pas limités à 0, 1 et 2 -
       vous pouvez spécifier n'importe quel numéro de descripteur valide, et
       il sera passé au processus fils. Cela permettra à votre script d'inter opérer
       avec d'autres scripts, et d'être exécuté comme "co-processus". En particulier,
       c'est très pratique pour passer des mots de passes à des programmes comme
       PGP, GPG et openssl, avec une méthode très protégée. C'est aussi pratique
       pour lire des informations de statut fournies par ces programmes, sur des
       descripteurs auxiliaires.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>pipes</parameter></term>
     <listitem>
      <para>
       Doit être défini en un tableau indexé de pointeurs de fichiers qui 
       correspondent à la fin de n'importe quel descripteur PHP qui sont
       créés.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>cwd</parameter></term>
     <listitem>
      <para>
       Le dossier initial de travail de la commande. Cela doit être
       un chemin <emphasis role="strong">absolu</emphasis>
       vers le dossier ou &null; si vous voulez utiliser la valeur
       par défaut (le dossier de travail du processus courant PHP)
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>env</parameter></term>
     <listitem>
      <para>
       Un tableau contenant les variables d'environnement pour la commande
       qui doit être exécutée, ou &null; pour utiliser le même environnement
       que le processus PHP courant
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>other_options</parameter></term>
     <listitem>
      <para>
       Vous permet de spécifier des options supplémentaires. Les options
       actuellement supportées sont :
       <simplelist>
        <member>
         <literal>suppress_errors</literal> (windows uniquement): suppression des
         erreurs générées par cette fonction lorsque définit à &true;
        </member>
        <member>
         <literal>bypass_shell</literal> (windows uniquement): bypass du shell
         <literal>cmd.exe</literal> lorsque définit à &true;
        </member>
        <member>
         <literal>context</literal>: contexte du flux utilisé lors de l'ouverture
         des fichiers (créé avec la fonction <function>stream_context_create</function>)
        </member>
        <member>
         <literal>binary_pipes</literal>: ouverture des pipes en mode binaire, au lieu
         d'utiliser l'encodage habituel <literal>stream_encoding</literal>
        </member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne une ressource représentant le processus, qui pourra être utilisé par 
   la fonction <function>proc_close</function> lorsque vous n'en aurez plus besoin.
   En cas d'échec, &false; sera retourné.
  </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>
        Ajout des options <literal>context</literal> et
        <literal>binary_pipes</literal> au paramètre
        <parameter>other_options</parameter>.
       </entry>
      </row>
      -->
      <row>
       <entry>5.2.1</entry>
       <entry>
        Ajout de l'option <literal>bypass_shell</literal> au paramètre
        <parameter>other_options</parameter>.
       </entry>
      </row>
      <row>
       <entry>5.0.0.</entry>
       <entry>
        Ajout des paramètres <parameter>cwd</parameter>, <parameter>env</parameter> et
        <parameter>other_options</parameter>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>proc_open</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$descriptorspec = array(
   0 => array("pipe", "r"),  // // stdin est un pipe où le processus va lire
   1 => array("pipe", "w"),  // stdout est un pipe où le processus va écrire
   2 => array("file", "/tmp/error-output.txt", "a") // stderr est un fichier
);

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

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

if (is_resource($process)) {
    // $pipes ressemble à :
    // 0 => fichier accessible en écriture, connecté à l'entrée standard du processus fils
    // 1 => fichier accessible en lecture, connecté à la sortie standard du processus fils
    // Toute erreur sera ajoutée au fichier /tmp/error-output.txt

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

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

    // Il est important que vous fermiez les pipes avant d'appeler
    // proc_close afin d'éviter un verrouillage.
    $return_value = proc_close($process);

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

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Compatibilité Windows : les descripteurs au-delà de 2 (stderr) sont
    accessibles au processus fils, sous la forme de pointeurs hérités, mais
    comme l'architecture Windows n'associe pas de nombre aux descripteurs
    de bas niveau, le processus fils n'a, actuellement, aucun moyen 
    d'y accéder. D'un autre coté, stdin, stdout et stderr fonctionnent
    comme d'habitude.
   </para>
  </note>
  <note>
   <para>
    Si vous n'avez besoin que d'un processus unidirectionnel,
    <function>popen</function> sera plus pratique, car plus simple à 
    utiliser.
   </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><link linkend="language.operators.execution">Les guillemets obliques</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
-->