Merge remote-tracking branch 'origin/debian'
[hcoop/debian/courier-authlib.git] / libs / liblock / lockmail.html
CommitLineData
d9898ee8 1<?xml version="1.0"?>
d50284c4 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" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"/><link rel="home" href="#idm255222393152" 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"/><!--
d9898ee8 3
b0322a85 4Copyright 1998 - 2009 Double Precision, Inc. See COPYING for distribution
d9898ee8 5information.
6
d50284c4 7--></head><body><div class="refentry"><a id="idm255222393152" 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"><a id="idm255226844240" shape="rect"> </a><h2>DESCRIPTION</h2><p>
8d138742 8<span class="command"><strong>lockmail</strong></span> is a helper utility for working with mailbox
d9898ee8 9files.
10Mailbox files must be locked to prevent other applications from modifying the
11mailbox at the same time.
12Different system use different locking conventions.
8d138742 13<span class="command"><strong>lockmail</strong></span> uses two of the most common locking mechanisms
d9898ee8 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.
8d138742 17By default, <span class="command"><strong>lockmail</strong></span> tries to lock the mailbox every
d9898ee8 18five seconds (if the mailbox is already locked), and will give up after
19three minutes.
b0322a85 20After the mailbox is successfully locked, <span class="command"><strong>lockmail</strong></span> runs
d9898ee8 21<em class="replaceable"><code>program</code></em> as a child process, with any optional
22<em class="replaceable"><code>argument</code></em>s.
8d138742 23When <em class="replaceable"><code>program</code></em> terminates, <span class="command"><strong>lockmail</strong></span>
d50284c4 24removes the mailbox lock, and terminates itself.</p></div><div class="refsect1"><a id="idm255221563024" shape="rect"> </a><h2>OPTIONS</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term">-r</span></dt><dd><p>
d9898ee8 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
d50284c4 30(a lock attempt is tried every five seconds).</p></dd></dl></div></div><div class="refsect1"><a id="idm255221557600" shape="rect"> </a><h2>DESCRIPTION</h2><p>
d9898ee8 31This section briefly describes the locking mechanism used by
8d138742
CE
32<span class="command"><strong>lockmail</strong></span>.
33<span class="command"><strong>lockmail</strong></span> uses three different locking conventions in
d9898ee8 34order to maximize compatibility with other mail software:
35C-Client folder locks, dot-locks, and file locks.
d50284c4 36</p><div class="refsect2"><a id="idm255221554944" shape="rect"> </a><h3>C-Client folder locks</h3><p>
d9898ee8 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,
8d138742 45<span class="command"><strong>lockmail</strong></span> concludes that it's a stale lock file, and
d9898ee8 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>
8d138742 53<span class="command"><strong>lockmail</strong></span>
d9898ee8 54attempts to resolve this race condition by deleting zero-length lock files
d50284c4 55that are at least five minutes old.</p></div></div><div class="refsect2"><a id="idm255221545360" shape="rect"> </a><h3>dot-locks</h3><p>
8d138742 56<span class="command"><strong>lockmail</strong></span>
d9898ee8 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.
8d138742 61<span class="command"><strong>lockmail</strong></span>
d9898ee8 62uses an enhanced method of dot-locking, where its process ID, and the name
8d138742 63of the server where <span class="command"><strong>lockmail</strong></span> is running is also saved
d9898ee8 64in its dot-lock file.
65If the operation fails due to an existing dot-lock file that was created
8d138742 66by another <span class="command"><strong>lockmail</strong></span> process on the same server, and the
d9898ee8 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
8d138742 73<span class="command"><strong>lockmail</strong></span>
d9898ee8 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
8d138742 79<span class="command"><strong>lockmail</strong></span>
d9898ee8 80will be content with using file-locking only.
d50284c4 81</p></div></div><div class="refsect2"><a id="idm255221536624" shape="rect"> </a><h3>File locks</h3><p>
d9898ee8 82The final locking mechanism
8d138742 83<span class="command"><strong>lockmail</strong></span>
d9898ee8 84uses is the operating system's file locking facility.
85If
8d138742 86<span class="command"><strong>lockmail</strong></span>
d9898ee8 87fails to obtain all three locks,
8d138742 88<span class="command"><strong>lockmail</strong></span>
d9898ee8 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
8d138742 93<span class="command"><strong>lockmail</strong></span>
d9898ee8 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),
8d138742 96<span class="command"><strong>lockmail</strong></span> will terminate with the
d9898ee8 97<code class="literal">EX_TEMPFAIL</code> exit code.
98</p><p>
8d138742 99<span class="command"><strong>lockmail</strong></span>
d9898ee8 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
8d138742
CE
104obtained by <span class="command"><strong>lockmail</strong></span> expire, and are considered stale.
105<span class="command"><strong>lockmail</strong></span> will then terminate with the same exit code
d50284c4 106as <em class="replaceable"><code>program</code></em>.</p></div></div><div class="refsect1"><a id="idm255221526144" shape="rect"> </a><h2>EXIT STATUS</h2><p>
8d138742 107<span class="command"><strong>lockmail</strong></span> terminates with the same exit status as
d9898ee8 108<em class="replaceable"><code>program</code></em>
8d138742 109<span class="command"><strong>lockmail</strong></span> terminates with the <code class="literal">EX_TEMPFAIL</code>
d9898ee8 110exit status if it was unable to obtain a lock, or if
111<em class="replaceable"><code>program</code></em>
d50284c4 112was killed by a signal.</p></div><div class="refsect1"><a id="idm255223766608" shape="rect"> </a><h2>SEE ALSO</h2><p>
8d138742 113<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>,
d9898ee8 114<span class="citerefentry"><span class="refentrytitle">sendmail</span>(8)</span>.
115</p></div></div></body></html>