flock.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0bfb0eb957e0468912af86bba09fae588010c1df Maintainer: HonestQiao Status: ready -->
<!-- CREDITS: lm92, mowangjuanzi -->
<refentry xml:id="function.flock" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>flock</refname>
  <refpurpose>可移植的协同文件锁定</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> 允许执行简单的读取/写入模型,该模型可以在任何平台（包括大部分
   Unix 衍生产品，甚至是 Windows）上使用。
  </para>
  <para>
   当调用 <function>fclose</function> 或者对 <parameter>stream</parameter> 垃圾收集时，锁会释放。
  </para>
  <para>
   PHP 支持以协同且可移植的方式锁定完整文件（也就是说所有访问程序必须使用相同锁定方式, 否则将无法工作）。默认情况下，该函数将堵塞直到获得锁；这可以通过下面文档中
   <constant>LOCK_NB</constant> 选项来控制。
  </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> 可以是以下值之一：
       <itemizedlist>
        <listitem>
         <simpara>
         <constant>LOCK_SH</constant>取得共享锁定（读取的程序）。
         </simpara>
        </listitem>
        <listitem>
         <simpara>
         <constant>LOCK_EX</constant> 取得独占锁定（写入的程序。
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LOCK_UN</constant> 释放锁定（无论共享或独占）。
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
      <para>
       It is also possible to add <constant>LOCK_NB</constant> as a bitmask to one 
       of the above operations, if <function>flock</function> should not
       block during the locking attempt.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>would_block</parameter></term>
     <listitem>
      <para>
       如果锁将堵塞（EWOULDBLOCK
       错误码情况下），第三个可选参数会设置为 1。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>flock</function> 例子</title>
    <programlisting role="php">
<![CDATA[
<?php

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

if (flock($fp, LOCK_EX)) {  // 进行排它型锁定
    ftruncate($fp, 0);      // truncate file
    fwrite($fp, "Write something here\n");
    fflush($fp);            // flush output before releasing the lock
    flock($fp, LOCK_UN);    // 释放锁定
} else {
    echo "Couldn't get the lock!";
}

fclose($fp);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>flock</function> 使用 <constant>LOCK_NB</constant> 选项</title>
    <programlisting role="php">
<![CDATA[
<?php
$fp = fopen('/tmp/lock.txt', 'r+');

/* Activate the LOCK_NB option on an LOCK_EX operation */
if(!flock($fp, LOCK_EX | LOCK_NB)) {
    echo 'Unable to obtain lock';
    exit(-1);
}

/* ... */

fclose($fp);
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    在 Windows 上，<function>flock</function> 使用的是强制锁而不是协同锁。
    Mandatory locking is also supported on Linux and
    System V based operating systems via the usual mechanism supported by the
    fcntl() system call: that is, if the file in question has the setgid
    permission bit set and the group execution bit cleared. On Linux, the file
    system will also need to be mounted with the mand option for this to work.
   </para>
  </note>
  <note>
   <para>
    由于 <function>flock</function>
    需要一个文件指针， 因此可能不得不用一个特殊的锁定文件来保护打算通过写模式打开的文件的访问（在
    <function>fopen</function> 函数中加入 "w" 或 "w+"）。
   </para>
  </note>
  <note>
   <para>
    只能用于 <function>fopen</function> 返回本地文件的文件指针，或指向实现
    <function>streamWrapper::stream_lock</function> 方法的用户空间流的文件指针。
   </para>
  </note>
  <warning>
   <para>
    在后续代码中为 <parameter>stream</parameter> 分配另一个值将释放锁。
   </para>
  </warning>
  <warning>
   <para>
    在部分操作系统中 <function>flock</function> 以进程级实现。当用多线程服务器
    API 时，可能无法依靠 <function>flock</function>
    来保护文件，因为运行于同一服务器实例中其它并行线程的 PHP 脚本可以对该文件进行处理！
   </para>
   <para>
    旧的文件系统（如 <literal>FAT</literal> 及其衍生）不支持
    <function>flock</function>，也因此在这些环境下总是返回 &false;。
   </para>
  </warning>
  <note>
   <para>
    在 Windows 上，如果锁进程再次打开文件，那么在解锁文件之前，无法通过第二个句柄访问文件。
   </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
-->