php-doc-en/reference/filesystem/functions/flock.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
  <refentry id="function.flock">
   <refnamediv>
    <refname>flock</refname>
    <refpurpose>Portable advisory file locking</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>flock</methodname>
      <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
      <methodparam><type>int</type><parameter>operation</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter role="reference">wouldblock</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     PHP supports a portable way of locking complete files in an
     advisory way (which means all accessing programs have to use the
     same way of locking or it will not work).
    </simpara>
    <note>
     <para>
      <function>flock</function> is mandatory under Windows.
     </para>
    </note>
    <simpara>
     <function>flock</function> operates on <parameter>handle</parameter>
     which must be an open file
     pointer. <parameter>operation</parameter> is one of the following
     values:
    </simpara>
    <para>
     <itemizedlist>
      <listitem>
       <simpara>
         To acquire a shared lock (reader), set
         <parameter>operation</parameter> to <constant>LOCK_SH</constant> (set to 1 prior to
         PHP 4.0.1).
       </simpara>
      </listitem>
      <listitem>
       <simpara>
         To acquire an exclusive lock (writer), set
         <parameter>operation</parameter> to <constant>LOCK_EX</constant> (set to 2 prior to
         PHP 4.0.1).
       </simpara>
      </listitem>
      <listitem>
       <simpara>
         To release a lock (shared or exclusive), set
         <parameter>operation</parameter> to <constant>LOCK_UN</constant> (set to 3 prior to
         PHP 4.0.1).
       </simpara>
      </listitem>
      <listitem>
       <simpara>
         If you don't want <function>flock</function> to block while
         locking, add <constant>LOCK_NB</constant> (4 prior to PHP 4.0.1) to
         <parameter>operation</parameter>.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <simpara>
     <function>flock</function> allows you to perform a simple
     reader/writer model which can be used on virtually every platform
     (including most Unix derivatives and even Windows).  The optional third
     argument is set to &true; if the lock would block (EWOULDBLOCK
     errno condition). The lock is released also by <function>fclose</function>
     (which is also called automatically when script finished).
    </simpara>
    <simpara>
      &return.success;
    </simpara>
    <para>
     <example>
      <title><function>flock</function> example</title>
      <programlisting role="php">
<![CDATA[
<?php

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

if (flock($fp, LOCK_EX)) { // do an exclusive lock
    fwrite($fp, "Write something here\n");
    flock($fp, LOCK_UN); // release the lock
} else {
    echo "Couldn't lock the file !";
}

fclose($fp);

?>
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <para>
      Because <function>flock</function> requires a file pointer, you may have
      to use a special lock file to protect access to a file that you intend
      to truncate by opening it in write mode (with a "w" or "w+" argument to
      <function>fopen</function>).
     </para>
    </note>
    <warning>
     <para>
      <function>flock</function> will not work on NFS and many other networked
      file systems. Check your operating system documentation for more
      details.
     </para>
     <para>
      On some operating systems <function>flock</function> is implemented at
      the process level. When using a multithreaded server API like ISAPI you
      may not be able to rely on <function>flock</function> to protect files
      against other PHP scripts running in parallel threads of the same server
      instance!
     </para>
     <para>
      <function>flock</function> is not supported on antiquated filesystems like
      <literal>FAT</literal> and its derivates and will therefore always
      return &false; under this environments (this is especially true for
      Windows 98 users).
     </para>
    </warning>
   </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:"../../../../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
-->