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=
"#idm247862818448" 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"/><!--
4 Copyright 1998 - 2009 Double Precision, Inc. See COPYING for distribution
7 --></head><body><div class=
"refentry"><a id=
"idm247862818448" 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=
"idm247862858048" shape=
"rect"> </a><h2>DESCRIPTION
</h2><p>
8 <span class=
"command"><strong>lockmail
</strong></span> is a helper utility for working with mailbox
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.
13 <span class=
"command"><strong>lockmail
</strong></span> uses two of the most common locking mechanisms
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
17 By default,
<span class=
"command"><strong>lockmail
</strong></span> tries to lock the mailbox every
18 five seconds (if the mailbox is already locked), and will give up after
20 After the mailbox is successfully locked,
<span class=
"command"><strong>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.
23 When
<em class=
"replaceable"><code>program
</code></em> terminates,
<span class=
"command"><strong>lockmail
</strong></span>
24 removes the mailbox lock, and terminates itself.
</p></div><div class=
"refsect1"><a id=
"idm247862850672" shape=
"rect"> </a><h2>OPTIONS
</h2><div class=
"variablelist"><dl class=
"variablelist"><dt><span class=
"term">-r
</span></dt><dd><p>
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
30 (a lock attempt is tried every five seconds).
</p></dd></dl></div></div><div class=
"refsect1"><a id=
"idm247862905792" shape=
"rect"> </a><h2>DESCRIPTION
</h2><p>
31 This section briefly describes the locking mechanism used by
32 <span class=
"command"><strong>lockmail
</strong></span>.
33 <span class=
"command"><strong>lockmail
</strong></span> uses three different locking conventions in
34 order to maximize compatibility with other mail software:
35 C-Client folder locks, dot-locks, and file locks.
36 </p><div class=
"refsect2"><a id=
"idm247862903136" shape=
"rect"> </a><h3>C-Client folder locks
</h3><p>
37 Mail software based on the
<code class=
"literal">C-Client
</code> library creates
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,
45 <span class=
"command"><strong>lockmail
</strong></span> concludes that it's a stale lock file, and
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
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
53 <span class=
"command"><strong>lockmail
</strong></span>
54 attempts to resolve this race condition by deleting zero-length lock files
55 that are at least five minutes old.
</p></div></div><div class=
"refsect2"><a id=
"idm247858665264" shape=
"rect"> </a><h3>dot-locks
</h3><p>
56 <span class=
"command"><strong>lockmail
</strong></span>
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.
61 <span class=
"command"><strong>lockmail
</strong></span>
62 uses an enhanced method of dot-locking, where its process ID, and the name
63 of the server where
<span class=
"command"><strong>lockmail
</strong></span> is running is also saved
65 If the operation fails due to an existing dot-lock file that was created
66 by another
<span class=
"command"><strong>lockmail
</strong></span> process on the same server, and the
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
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
73 <span class=
"command"><strong>lockmail
</strong></span>
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
79 <span class=
"command"><strong>lockmail
</strong></span>
80 will be content with using file-locking only.
81 </p></div></div><div class=
"refsect2"><a id=
"idm247858656528" shape=
"rect"> </a><h3>File locks
</h3><p>
82 The final locking mechanism
83 <span class=
"command"><strong>lockmail
</strong></span>
84 uses is the operating system's file locking facility.
86 <span class=
"command"><strong>lockmail
</strong></span>
87 fails to obtain all three locks,
88 <span class=
"command"><strong>lockmail
</strong></span>
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.
93 <span class=
"command"><strong>lockmail
</strong></span>
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),
96 <span class=
"command"><strong>lockmail
</strong></span> will terminate with the
97 <code class=
"literal">EX_TEMPFAIL
</code> exit code.
99 <span class=
"command"><strong>lockmail
</strong></span>
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
103 <em class=
"replaceable"><code>program
</code></em> must terminate before any of the locks
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
106 as
<em class=
"replaceable"><code>program
</code></em>.
</p></div></div><div class=
"refsect1"><a id=
"idm247862945792" shape=
"rect"> </a><h2>EXIT STATUS
</h2><p>
107 <span class=
"command"><strong>lockmail
</strong></span> terminates with the same exit status as
108 <em class=
"replaceable"><code>program
</code></em>
109 <span class=
"command"><strong>lockmail
</strong></span> terminates with the
<code class=
"literal">EX_TEMPFAIL
</code>
110 exit status if it was unable to obtain a lock, or if
111 <em class=
"replaceable"><code>program
</code></em>
112 was killed by a signal.
</p></div><div class=
"refsect1"><a id=
"idm247862941632" shape=
"rect"> </a><h2>SEE ALSO
</h2><p>
113 <a class=
"ulink" 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>