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