popen.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0c9c2dd669fe9395eaa73d487fbd160f9057429a Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.popen" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>popen</refname>
  <refpurpose>Crée un processus de pointeur de fichier</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>resource</type><type>false</type></type><methodname>popen</methodname>
   <methodparam><type>string</type><parameter>command</parameter></methodparam>
   <methodparam><type>string</type><parameter>mode</parameter></methodparam>
  </methodsynopsis>
  <para>
   Crée un processus de pointeur de fichier, exécuté en effectuant un fork
   de la commande fournie par le paramètre <parameter>command</parameter>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>command</parameter></term>
     <listitem>
      <para>
       La commande
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       Le mode. Soit <literal>'r'</literal> pour lecture, soit <literal>'w'</literal>
       pour l'écriture.
      </para>
      <para>
       Sur Windows, <function>popen</function> utilise le mode texte par défaut,
       c.à.d. tout caractères <literal>\n</literal> écrit ou lu du pipe sera
       traduit en <literal>\r\n</literal>.
       Si ceci n'est pas désiré, le mode binaire peut être enforcé en définissant
       le <parameter>mode</parameter> à <literal>'rb'</literal> et
       <literal>'wb'</literal>, respectivement.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne un pointeur de fichier identique à celui retourné par
   <function>fopen</function>, hormis le fait qu'il sera
   unidirectionnel (lecture seule, ou écriture seule), et doit être
   terminé par <function>pclose</function>. Ce pointeur peut être
   utilisé avec <function>fgets</function>, <function>fgetss</function>
   et <function>fwrite</function>. Lorsque le mode est 'r', le pointeur
   de fichier retourné équivaut au STDOUT de la commande, et lorsque
   le mode est 'w', le pointeur de fichier retourné équivaut au
   STDIN de la commande.
  </para>
  <para>
   Si une erreur survient, la fonction retournera &false;.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>popen</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$handle = popen("/bin/ls", "r");
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Si la commande à exécuter n'a pu être trouvée, une ressource
   valide sera retournée. Cela semble étrange, mais c'est pratique.
   cela vous permet d'accéder aux messages d'erreur qui ont été
   retournés par le Shell :
   <example>
    <title>Exemple avec <function>popen</function></title>
    <programlisting role="php">
<![CDATA[
<?php
error_reporting(E_ALL);

/* Ajoute une redirection pour que vous puissiez lire stderr. */
$handle = popen('/path/to/executable 2>&1', 'r');
echo "'$handle'; " . gettype($handle) . "\n";
$read = fread($handle, 2096);
echo $read;
pclose($handle);
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Si vous souhaitez un support bidirectionnel (two-way), utilisez
    la fonction <function>proc_open</function>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>pclose</function></member>
    <member><function>fopen</function></member>
    <member><function>proc_open</function></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
-->