/usr/share/doc/maildrop/html/lockmail.html is in maildrop 2.5.5-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | <?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>lockmail</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"/><link rel="home" href="#id502581" title="lockmail"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--
Copyright 1998 - 2009 Double Precision, Inc. See COPYING for distribution
information.
--></head><body><div class="refentry" title="lockmail"><a id="id502581" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>lockmail — create mail lock files</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">lockmail</code> [-r] [-t <em class="replaceable"><code>timeout</code></em>] {<em class="replaceable"><code>lockfile</code></em>} {<em class="replaceable"><code>program</code></em>} [argument...]</p></div></div><div class="refsect1" title="DESCRIPTION"><a id="id502356" shape="rect"> </a><h2>DESCRIPTION</h2><p>
<span class="command"><strong>lockmail</strong></span> is a helper utility for working with mailbox
files.
Mailbox files must be locked to prevent other applications from modifying the
mailbox at the same time.
Different system use different locking conventions.
<span class="command"><strong>lockmail</strong></span> uses two of the most common locking mechanisms
in use, which should work reliably on most systems.</p><p>
<em class="replaceable"><code>lockfile</code></em> is the pathname to an existing mailbox
file.
By default, <span class="command"><strong>lockmail</strong></span> tries to lock the mailbox every
five seconds (if the mailbox is already locked), and will give up after
three minutes.
After the mailbox is successfully locked, <span class="command"><strong>lockmail</strong></span> runs
<em class="replaceable"><code>program</code></em> as a child process, with any optional
<em class="replaceable"><code>argument</code></em>s.
When <em class="replaceable"><code>program</code></em> terminates, <span class="command"><strong>lockmail</strong></span>
removes the mailbox lock, and terminates itself.</p></div><div class="refsect1" title="OPTIONS"><a id="id536844" shape="rect"> </a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term">-r</span></dt><dd><p>
If a regular lock fails, try a read-only lock.
Use this option to lock mailbox files in a read-only directory.</p></dd><dt><span class="term">-t <em class="replaceable"><code>timeout</code></em></span></dt><dd><p>
If the lock attempt fails, try again for up to
<em class="replaceable"><code>timeout</code></em> seconds.
The actual timeout is rounded up to the next five second interval
(a lock attempt is tried every five seconds).</p></dd></dl></div></div><div class="refsect1" title="DESCRIPTION"><a id="id536889" shape="rect"> </a><h2>DESCRIPTION</h2><p>
This section briefly describes the locking mechanism used by
<span class="command"><strong>lockmail</strong></span>.
<span class="command"><strong>lockmail</strong></span> uses three different locking conventions in
order to maximize compatibility with other mail software:
C-Client folder locks, dot-locks, and file locks.
</p><div class="refsect2" title="C-Client folder locks"><a id="id536911" shape="rect"> </a><h3>C-Client folder locks</h3><p>
Mail software based on the <code class="literal">C-Client</code> library creates
lock files named
<code class="filename">/tmp/.<em class="replaceable"><code>dddddd</code></em>.<em class="replaceable"><code>iiiiii</code></em></code>.
Here, <em class="replaceable"><code>dddddd</code></em> and <em class="replaceable"><code>iiiiii</code></em>
are the device number and the inode number of the mailbox file
(the <em class="structfield"><code>st_dev</code></em> and <em class="structfield"><code>st_ino</code></em>
fields in the inode), in hexadecimal.
If the process ID saved in the C-Client folder lock file is not valid,
<span class="command"><strong>lockmail</strong></span> concludes that it's a stale lock file, and
will remove it.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
A race condition exists where a <code class="literal">C-Client</code> process is
killed after it creates a lock file, but before saving its process ID in the
lock file.
The race window is very small, but it exists.
The <code class="literal">C-Client</code> library does not appear to ever clear out
the lock file.</p><p>
<span class="command"><strong>lockmail</strong></span>
attempts to resolve this race condition by deleting zero-length lock files
that are at least five minutes old.</p></div></div><div class="refsect2" title="dot-locks"><a id="id501488" shape="rect"> </a><h3>dot-locks</h3><p>
<span class="command"><strong>lockmail</strong></span>
also creates, and honors dot-lock files.
Dot-lock files are first created as temporary files, then linked to
<code class="filename"><em class="replaceable"><code>lockfile</code></em>.lock</code>.
The link operation fails if the dot-lock file already exists.
<span class="command"><strong>lockmail</strong></span>
uses an enhanced method of dot-locking, where its process ID, and the name
of the server where <span class="command"><strong>lockmail</strong></span> is running is also saved
in its dot-lock file.
If the operation fails due to an existing dot-lock file that was created
by another <span class="command"><strong>lockmail</strong></span> process on the same server, and the
process ID no longer exists, this stale dot-lock file is removed immediately.
In all other situations a dot-lock file older than five minutes is considered
stale, and removed.
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
A failure to create a dot-lock file is silently ignored if the reason for
the failure is because
<span class="command"><strong>lockmail</strong></span>
does not have the write permission in the dot-lock file's directory.
The incoming mail spool directory (usually
<code class="filename">/var/mail</code>)
typically does not have global write permissions, so the attempt to
create the dot-lock file in the spool directory will fail, and
<span class="command"><strong>lockmail</strong></span>
will be content with using file-locking only.
</p></div></div><div class="refsect2" title="File locks"><a id="id501562" shape="rect"> </a><h3>File locks</h3><p>
The final locking mechanism
<span class="command"><strong>lockmail</strong></span>
uses is the operating system's file locking facility.
If
<span class="command"><strong>lockmail</strong></span>
fails to obtain all three locks,
<span class="command"><strong>lockmail</strong></span>
will sleep for five seconds and try again.
The only exception is a failure to create a dot-lock because of no write
access to the dot-lock file's directory, which is ignored.
If
<span class="command"><strong>lockmail</strong></span>
still fails to obtain all required locks in the amount of time specified
by the <code class="option">-t</code> option (or its default value),
<span class="command"><strong>lockmail</strong></span> will terminate with the
<code class="literal">EX_TEMPFAIL</code> exit code.
</p><p>
<span class="command"><strong>lockmail</strong></span>
runs <em class="replaceable"><code>program</code></em> after obtaining the last file
lock, waits until <em class="replaceable"><code>program</code></em> terminates, and
releases all locks.
<em class="replaceable"><code>program</code></em> must terminate before any of the locks
obtained by <span class="command"><strong>lockmail</strong></span> expire, and are considered stale.
<span class="command"><strong>lockmail</strong></span> will then terminate with the same exit code
as <em class="replaceable"><code>program</code></em>.</p></div></div><div class="refsect1" title="EXIT STATUS"><a id="id501782" shape="rect"> </a><h2>EXIT STATUS</h2><p>
<span class="command"><strong>lockmail</strong></span> terminates with the same exit status as
<em class="replaceable"><code>program</code></em>
<span class="command"><strong>lockmail</strong></span> terminates with the <code class="literal">EX_TEMPFAIL</code>
exit status if it was unable to obtain a lock, or if
<em class="replaceable"><code>program</code></em>
was killed by a signal.</p></div><div class="refsect1" title="SEE ALSO"><a id="id501816" shape="rect"> </a><h2>SEE ALSO</h2><p>
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>,
<span class="citerefentry"><span class="refentrytitle">sendmail</span>(8)</span>.
</p></div></div></body></html>
|