<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Portable advisory file locking</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.filetype.html">filetype</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.fnmatch.html">fnmatch</a></div>
<div class="up"><a href="ref.filesystem.html">Filesystem Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.flock" class="refentry">
<div class="refnamediv">
<h1 class="refname">flock</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">flock</span> — <span class="dc-title">Portable advisory file locking</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.flock-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">bool</span> <span class="methodname"><strong>flock</strong></span>
( <span class="methodparam"><span class="type">resource</span> <code class="parameter">$handle</code></span>
, <span class="methodparam"><span class="type">int</span> <code class="parameter">$operation</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter reference">&$wouldblock</code></span>
] )</div>
<p class="para rdfs-comment">
<span class="function"><strong>flock()</strong></span> allows you to perform a simple reader/writer
model which can be used on virtually every platform (including most Unix
derivatives and even Windows).
</p>
<p class="para">
On versions of PHP before 5.3.2, the lock is released also by
<span class="function"><a href="function.fclose.html" class="function">fclose()</a></span> (which is also called automatically when script
finished).
</p>
<p class="para">
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). By default, this function will block until the
requested lock is acquired; this may be controlled (on non-Windows
platforms) with the <strong><code>LOCK_NB</code></strong> option documented below.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.flock-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">handle</code></em></span>
<dd>
<p class="para">A file system pointer <span class="type"><a href="language.types.resource.html" class="type resource">resource</a></span>
that is typically created using <span class="function"><a href="function.fopen.html" class="function">fopen()</a></span>.</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">operation</code></em></span>
<dd>
<p class="para">
<em><code class="parameter">operation</code></em> is one of the following:
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
<strong><code>LOCK_SH</code></strong> to acquire a shared lock (reader).
</span>
</li>
<li class="listitem">
<span class="simpara">
<strong><code>LOCK_EX</code></strong> to acquire an exclusive lock (writer).
</span>
</li>
<li class="listitem">
<span class="simpara">
<strong><code>LOCK_UN</code></strong> to release a lock (shared or exclusive).
</span>
</li>
</ul>
</p>
<p class="para">
It is also possible to add <strong><code>LOCK_NB</code></strong> as a bitmask to one
of the above operations if you don't want <span class="function"><strong>flock()</strong></span> to
block while locking. (not supported on Windows)
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">wouldblock</code></em></span>
<dd>
<p class="para">
The optional third argument is set to 1 if the lock would block
(EWOULDBLOCK errno condition). (not supported on Windows)
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.flock-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.flock-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>5.3.2</td>
<td>
The automatic unlocking when the file's resource handle is closed was
removed. Unlocking now always has to be done manually.
</td>
</tr>
<tr>
<td>4.0.1</td>
<td>
The <em>LOCK_XXX</em> constants were added. Prior to that
you must use 1 for <strong><code>LOCK_SH</code></strong>, 2 for
<strong><code>LOCK_EX</code></strong>, 3 for <strong><code>LOCK_UN</code></strong> and
4 for <strong><code>LOCK_NB</code></strong>
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.flock-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-2382">
<p><strong>Example #1 <span class="function"><strong>flock()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$fp </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">"/tmp/lock.txt"</span><span style="color: #007700">, </span><span style="color: #DD0000">"r+"</span><span style="color: #007700">);<br /><br />if (</span><span style="color: #0000BB">flock</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #0000BB">LOCK_EX</span><span style="color: #007700">)) { </span><span style="color: #FF8000">// acquire an exclusive lock<br /> </span><span style="color: #0000BB">ftruncate</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #0000BB">0</span><span style="color: #007700">); </span><span style="color: #FF8000">// truncate file<br /> </span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">"Write something here\n"</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">fflush</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">); </span><span style="color: #FF8000">// flush output before releasing the lock<br /> </span><span style="color: #0000BB">flock</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #0000BB">LOCK_UN</span><span style="color: #007700">); </span><span style="color: #FF8000">// release the lock<br /></span><span style="color: #007700">} else {<br /> echo </span><span style="color: #DD0000">"Couldn't get the lock!"</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-2383">
<p><strong>Example #2 <span class="function"><strong>flock()</strong></span> using the <strong><code>LOCK_NB</code></strong> option</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$fp </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">'/tmp/lock.txt'</span><span style="color: #007700">, </span><span style="color: #DD0000">'r+'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* Activate the LOCK_NB option on an LOCK_EX operation */<br /></span><span style="color: #007700">if(!</span><span style="color: #0000BB">flock</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #0000BB">LOCK_EX </span><span style="color: #007700">| </span><span style="color: #0000BB">LOCK_NB</span><span style="color: #007700">)) {<br /> echo </span><span style="color: #DD0000">'Unable to obtain lock'</span><span style="color: #007700">;<br /> exit(-</span><span style="color: #0000BB">1</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #FF8000">/* ... */<br /><br /></span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 notes" id="refsect1-function.flock-notes">
<h3 class="title">Notes</h3>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
<span class="function"><strong>flock()</strong></span> uses mandatory locking instead of advisory
locking on Windows. 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.
</p>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Because <span class="function"><strong>flock()</strong></span> 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
<span class="function"><a href="function.fopen.html" class="function">fopen()</a></span>).
</p>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
May only be used on file pointers returned by <span class="function"><a href="function.fopen.html" class="function">fopen()</a></span>
for local files, or file pointers pointing to userspace streams that
implement the <span class="function"><a href="streamwrapper.stream-lock.html" class="function">streamWrapper::stream_lock()</a></span> method.
</p>
</p></blockquote>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
Assigning another value to <em><code class="parameter">handle</code></em> argument in
subsequent code will release the lock.
</p>
</div>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
On some operating systems <span class="function"><strong>flock()</strong></span> is implemented at
the process level. When using a multithreaded server API like ISAPI you
may not be able to rely on <span class="function"><strong>flock()</strong></span> to protect files
against other PHP scripts running in parallel threads of the same server
instance!
</p>
<p class="para">
<span class="function"><strong>flock()</strong></span> is not supported on antiquated filesystems like
<em>FAT</em> and its derivates and will therefore always
return <strong><code>FALSE</code></strong> under this environments (this is especially true for
Windows 98 users).
</p>
</div>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.filetype.html">filetype</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.fnmatch.html">fnmatch</a></div>
<div class="up"><a href="ref.filesystem.html">Filesystem Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
