doc-fr/reference/filesystem/functions/flock.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0bfb0eb957e0468912af86bba09fae588010c1df Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.flock" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>flock</refname>
  <refpurpose>Verrouille le fichier</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>flock</methodname>
   <methodparam><type>resource</type><parameter>stream</parameter></methodparam>
   <methodparam><type>int</type><parameter>operation</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter role="reference">would_block</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>flock</function> permet de réaliser un système simple de
   verrous écriture/lecture, qui peut être utilisé sur
   n'importe quelle plate-forme (Unix et Windows compris).
  </para>
  <para>
   Le verrou est également levé avec <function>fclose</function>,
   ou quand <parameter>stream</parameter> est ramassé par le ramasse-miette.
  </para>
  <para>
   PHP dispose d'un système complet de verrouillage de fichiers.
   Tous les programmes qui accèdent au fichier doivent utiliser la
   même méthode de verrouillage pour qu'il soit efficace. Par
   défaut, cette fonction se bloquera tant que le verrou demandé
   ne sera pas acquis ; ce comportement peut être contrôlé avec l'option <constant>LOCK_NB</constant>
   dont vous trouverez la documentation ci-dessous.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>stream</parameter></term>
     <listitem>
      &fs.file.pointer;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>operation</parameter></term>
     <listitem>
      <para>
       <parameter>operation</parameter> peut prendre une des valeurs suivantes :
       <itemizedlist>
        <listitem>
         <simpara>
          <constant>LOCK_SH</constant> pour acquérir un verrou partagé (lecture).
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LOCK_EX</constant> pour acquérir un verrou exclusif (écriture).
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LOCK_UN</constant> pour libérer un verrou (partagé ou exclusif).
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
      <para>
       Il est également possible d'ajouter <constant>LOCK_NB</constant>
       comme masque d'une des opérations précédentes si vous ne
       voulez pas que la fonction <function>flock</function> bloque durant
       le verrouillage.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>would_block</parameter></term>
     <listitem>
      <para>
       Ce troisième argument optionnel est défini à 1 si le verrou
       doit bloquer le script (condition d'erreur <literal>EWOULDBLOCK</literal>).
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>flock</function></title>
    <programlisting role="php">
<![CDATA[
<?php

$fp = fopen("/tmp/lock.txt", "r+");

if (flock($fp, LOCK_EX)) { // acquière un verrou exclusif
    ftruncate($fp, 0);     // effacement du contenu
    fwrite($fp, "Écrire dans un fichier\n");
    fflush($fp);            // libère le contenu avant d'enlever le verrou
    flock($fp, LOCK_UN);    // Enlève le verrou
} else {
    echo "Impossible de verrouiller le fichier !";
}

fclose($fp);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Exemple avec <function>flock</function> en utilisant l'option <constant>LOCK_NB</constant></title>
    <programlisting role="php">
<![CDATA[
<?php
$fp = fopen('/tmp/lock.txt', 'r+');

/* Activation de l'option LOCK_NB lors d'une opération LOCK_EX */
if(!flock($fp, LOCK_EX | LOCK_NB)) {
    echo 'Impossible d\'obtenir le verrou';
    exit(-1);
}

/* ... */

fclose($fp);
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    <function>flock</function> utilise les verrous obligatoires sous Windows, qui sont
    aussi supportés sur Linux et les systèmes dérivés de System V au moyen de l'appel
    système fcntl(): si le fichier en question a le bit setgid positionné et le bit
    de groupe vide. Sur Linux, le système de fichiers devra être monté avec l'option
    mand pour que cela fonctionne.
   </para>
  </note>
  <note>
   <para>
    Comme <function>flock</function> requiert un pointeur de fichier, vous 
    aurez peut être à utiliser un verrou spécial pour protéger l'accès au fichier
    que vous voulez tronquer en l'ouvrant en mode d'écriture (avec "w" ou "w+" 
    comme argument de <function>fopen</function>).
   </para>
  </note>
  <note>
   <para>
    Ne devrait être utilisé que sur des ressources issues de <function>fopen</function>
    pour des fichiers locaux ou via le gestionnaire de flux personnalisé en définissant
    <function>streamWrapper::stream_lock</function>. 
   </para>
  </note>
  <warning>
   <para>
    Assigner une autre valeur à l'argument <parameter>stream</parameter>
    dans ce code libèrera le verrou.
   </para>
  </warning>
  <warning>
   <para>
    Sur certains systèmes d'exploitation, <function>flock</function> est implémenté
    au niveau processus. Lorsque vous utilisez une API multithread, vous risquez de
    ne pas pouvoir avoir confiance en <function>flock</function> pour protéger vos
    fichiers contre d'autres scripts PHP qui fonctionnent en parallèle sur d'autres
    threads du même serveur.
   </para>
   <para>
    <function>flock</function> n'est pas supporté sur les vieux systèmes de fichiers
    comme <literal>FAT</literal> et ses dérivés, et elle retournera forcément
    &false; sous ces environnements.
   </para>
  </warning>
  <note>
   <para>
    Sur Windows, si la procédure de verrou ouvre une fichier une deuxième fois,
    il ne peut pas accéder au fichier à travers ce gestionnaire jusqu'à ce
    le fichier soit déverrouillé.
   </para>
  </note>
 </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
-->