Commit | Line | Data |
---|---|---|
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 | 4 | Copyright 1998 - 2009 Double Precision, Inc. See COPYING for distribution |
d9898ee8 | 5 | information. |
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 | 9 | files. |
10 | Mailbox files must be locked to prevent other applications from modifying the | |
11 | mailbox at the same time. | |
12 | Different system use different locking conventions. | |
8d138742 | 13 | <span class="command"><strong>lockmail</strong></span> uses two of the most common locking mechanisms |
d9898ee8 | 14 | in 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 | |
16 | file. | |
8d138742 | 17 | By default, <span class="command"><strong>lockmail</strong></span> tries to lock the mailbox every |
d9898ee8 | 18 | five seconds (if the mailbox is already locked), and will give up after |
19 | three minutes. | |
b0322a85 | 20 | After 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 | 23 | When <em class="replaceable"><code>program</code></em> terminates, <span class="command"><strong>lockmail</strong></span> |
d50284c4 | 24 | removes 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 | 25 | If a regular lock fails, try a read-only lock. |
26 | 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> | |
27 | If the lock attempt fails, try again for up to | |
28 | <em class="replaceable"><code>timeout</code></em> seconds. | |
29 | The 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 | 31 | This 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 | 34 | order to maximize compatibility with other mail software: |
35 | C-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 | 37 | Mail software based on the <code class="literal">C-Client</code> library creates |
38 | lock files named | |
39 | <code class="filename">/tmp/.<em class="replaceable"><code>dddddd</code></em>.<em class="replaceable"><code>iiiiii</code></em></code>. | |
40 | Here, <em class="replaceable"><code>dddddd</code></em> and <em class="replaceable"><code>iiiiii</code></em> | |
41 | are 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> | |
43 | fields in the inode), in hexadecimal. | |
44 | If 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 | 46 | will remove it.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
47 | A race condition exists where a <code class="literal">C-Client</code> process is | |
48 | killed after it creates a lock file, but before saving its process ID in the | |
49 | lock file. | |
50 | The race window is very small, but it exists. | |
51 | The <code class="literal">C-Client</code> library does not appear to ever clear out | |
52 | the lock file.</p><p> | |
8d138742 | 53 | <span class="command"><strong>lockmail</strong></span> |
d9898ee8 | 54 | attempts to resolve this race condition by deleting zero-length lock files |
d50284c4 | 55 | that 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 | 57 | also creates, and honors dot-lock files. |
58 | Dot-lock files are first created as temporary files, then linked to | |
59 | <code class="filename"><em class="replaceable"><code>lockfile</code></em>.lock</code>. | |
60 | The link operation fails if the dot-lock file already exists. | |
8d138742 | 61 | <span class="command"><strong>lockmail</strong></span> |
d9898ee8 | 62 | uses an enhanced method of dot-locking, where its process ID, and the name |
8d138742 | 63 | of the server where <span class="command"><strong>lockmail</strong></span> is running is also saved |
d9898ee8 | 64 | in its dot-lock file. |
65 | If the operation fails due to an existing dot-lock file that was created | |
8d138742 | 66 | by another <span class="command"><strong>lockmail</strong></span> process on the same server, and the |
d9898ee8 | 67 | process ID no longer exists, this stale dot-lock file is removed immediately. |
68 | In all other situations a dot-lock file older than five minutes is considered | |
69 | stale, and removed. | |
70 | </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | |
71 | A failure to create a dot-lock file is silently ignored if the reason for | |
72 | the failure is because | |
8d138742 | 73 | <span class="command"><strong>lockmail</strong></span> |
d9898ee8 | 74 | does not have the write permission in the dot-lock file's directory. |
75 | The incoming mail spool directory (usually | |
76 | <code class="filename">/var/mail</code>) | |
77 | typically does not have global write permissions, so the attempt to | |
78 | create the dot-lock file in the spool directory will fail, and | |
8d138742 | 79 | <span class="command"><strong>lockmail</strong></span> |
d9898ee8 | 80 | will 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 | 82 | The final locking mechanism |
8d138742 | 83 | <span class="command"><strong>lockmail</strong></span> |
d9898ee8 | 84 | uses is the operating system's file locking facility. |
85 | If | |
8d138742 | 86 | <span class="command"><strong>lockmail</strong></span> |
d9898ee8 | 87 | fails to obtain all three locks, |
8d138742 | 88 | <span class="command"><strong>lockmail</strong></span> |
d9898ee8 | 89 | will sleep for five seconds and try again. |
90 | The only exception is a failure to create a dot-lock because of no write | |
91 | access to the dot-lock file's directory, which is ignored. | |
92 | If | |
8d138742 | 93 | <span class="command"><strong>lockmail</strong></span> |
d9898ee8 | 94 | still fails to obtain all required locks in the amount of time specified |
95 | by 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 | 100 | runs <em class="replaceable"><code>program</code></em> after obtaining the last file |
101 | lock, waits until <em class="replaceable"><code>program</code></em> terminates, and | |
102 | releases all locks. | |
103 | <em class="replaceable"><code>program</code></em> must terminate before any of the locks | |
8d138742 CE |
104 | obtained 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 | 106 | as <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 | 110 | exit status if it was unable to obtain a lock, or if |
111 | <em class="replaceable"><code>program</code></em> | |
d50284c4 | 112 | was 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> |