/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/File-TinyLock/blib/html/site/lib/File/TinyLock.html

DESCRIPTION</pre>

DESCRIPTION</pre> <code>File::TinyLock</code> provides a <a href=``#lock''><code>lock</code></a>, <code>unlock</code>, and <code>check</code> function for working with file locks. <hr /> <h1><a name=``constructor''>CONSTRUCTOR</a></h1> <dl> <dt><a name=``lock'' class=``item''>lock( [FILE] [,OPTIONS] );</a>

<dd> If <code>FIL&FIL;/code> is not given, then it may instead be passed as the <code>file</code> option described below. </dd> <dd> <code>OPTION/code are passed in a hash like fashion, using key and value pairs. Possible options are: </dd> <dd> file - The file to lock </dd> <dd> timeout - Number of seconds to continue trying to lock (Default: 10). </dd> <dd> debug - Print debugging info to STDERR (0=Off, 1=On). </dd> </li> </dl> <hr /> <h1><a name=``return_value''>RETURN VALU&RETURN VALU;/a></h1> Here are a list of return codes of the <a href=``#lock''><code>lock</code></a> function and what they mean: <ol> <li><a name=``the_file_is_locked'' class=``item''>The file is locked.</a>

<li><a name=``the_file_is_not_found'' class=``item''>The file is not found.</a>

<li><a name=``master_lock_exists_and_is_not_writable'' class=``item''>Master lock exists and is not writable</a>

<li><a name=``could_not_unlink_stale_master_lock'' class=``item''>Could not unlink stale master lock</a>

<li><a name=``could_not_fork_ps'' class=``item''>Could not fork ps</a>

<li><a name=``could_not_read_master_lock'' class=``item''>Could not read master lock</a>

<li><a name=``could_not_write_to_temporary_lock'' class=``item''>Could not write to temporary lock</a>

<li><a name=``the_file_is_already_locked'' class=``item''>The file is already locked.</a>

.. and for the <code>check</code> function: </li> <li><a name=``file_is_locked'' class=``item''>File is locked</a>

<li><a name=``file_is_not_locked'' class=``item''>File is not locked</a>

<li><a name=``permissions_problems_with_lock_files'' class=``item''>permissions problems with lock files</a>

.. and the <code>unlock</code> function: </li> <li><a name=``file_unlocked'' class=``item''>File unlocked.</a>

<li><a name=``couldnt_unlock_file'' class=``item''>Couldnt unlock file</a>

<li><a name=``couldnt_unlink_master_lock'' class=``item''>Couldnt unlink master lock</a>

<li><a name=``couldnt_unlink_temporary_lock'' class=``item''>Couldnt unlink temporary lock</a>

</ol> <hr /> <h1><a name=``examples''>EXAMPLE/a</h1> <pre> use File::TinyLock; my $file = shift; unless(defined($file)){ print ``file to lock: ''; chop($file=<STDIN>); } my $result = File::TinyLock::lock($file); if($result){ print ``Could not lock: ${result}\n''; }else{ print ``$file is now locked\n''; }


        <span class="comment"># do stuff to file</span>
</pre>
<pre>
  <span class="keyword">if</span><span class="operator">(</span><span class="variable">$result</span> <span class="operator">=</span> <span class="variable">File::TinyLock::unlock</span><span class="operator">(</span><span class="variable">$file</span><span class="operator">)){</span>
    <span class="keyword">print</span> <span class="string">"could not unlock </span><span class="variable">$file</span><span class="string">: </span><span class="variable">$result</span><span class="string">\n"</span><span class="operator">;</span>
  <span class="operator">}</span>
  <span class="keyword">exit</span><span class="operator">;</span>
</pre>
<p>
</p>
<hr />
<h1><a name="caveats">CAVEATS</a></h1>
<p>This utility must be used by all code that works with the file you're
trying to lock.  Locking with <code>File::TinyLock</code> will not keep someone
from using vi and editing the file.</p>
<p>If you leave lock files around (from not unlocking the file before
your code exits), <code>File::TinyLock</code> will try its best to determine if the
lock files are stale or not.  This is best effort, and may yield
false positives.  For example, if your code was running as pid 1234
and exited without unlocking, stale detection may fail if there is
a new process running with pid 1234.</p>
<p>
</p>
<hr />
<h1><a name="restrictions">RESTRICTIONS</a></h1>
<p>Locking will only remain successfull while your code is active.  You
can not lock a file, let your code exit, and expect the file to remain
locked; doing so will result in stale lock files left behind.</p>
<p>lock file -&gt; do stuff -&gt; unlock file -&gt; exit;</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>&lt;a href=&quot;http://jeremy.kister.net./&;quot;&gt;Jeremy Kister&lt;/a&gt;</p>

</body>

</html>

/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/File-TinyLock/blib/html/site/lib/File/TinyLock.html