liblock/lockmail.html

   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.73.2"/><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
   4 Copyright 1998 - 2007 Double Precision, Inc.  See COPYING for distribution
   5 information.
   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="id401215" shape="rect"> </a><h2>DESCRIPTION</h2><p>
   8 <span class="command"><strong>lockmail</strong></span> is a helper utility for working with mailbox
   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.
  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
  16 file.
  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
  19 three minutes.
  20 After the mailbox is succesfully 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" lang="en" xml:lang="en"><a id="id366992" shape="rect"> </a><h2>OPTIONS</h2><div class="variablelist"><dl><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" lang="en" xml:lang="en"><a id="id366015" 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" lang="en" xml:lang="en"><a id="id366036" shape="rect"> </a><h3>C-Client folder locks</h3><p>
  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,
  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
  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>
  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" lang="en" xml:lang="en"><a id="id366638" 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
  64 in its dot-lock file.
  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
  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
  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" lang="en" xml:lang="en"><a id="id366198" 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.
  85 If
  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.
  92 If
  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.
  98 </p><p>
  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
 102 releases all locks.
 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" lang="en" xml:lang="en"><a id="id366286" 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" lang="en" xml:lang="en"><a id="id366320" 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>