liblock/lockmail.1

   1 .\"  <!-- $Id: lockmail.sgml,v 1.8 2007/04/22 15:05:16 mrsam Exp $ -->
   2 .\"  <!-- Copyright 2002-2007 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: lockmail
   5 .\"    Author:
   6 .\" Generator: DocBook XSL Stylesheets v1.72.0 <http://docbook.sf.net/>
   7 .\"      Date: 04/22/2007
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"
  11 .TH "LOCKMAIL" "1" "04/22/2007" "Double Precision, Inc." "Double Precision, Inc."
  12 .\" disable hyphenation
  13 .nh
  14 .\" disable justification (adjust text to left margin only)
  15 .ad l
  16 .SH "NAME"
  17 lockmail \- create mail lock files
  18 .SH "SYNOPSIS"
  19 .HP 9
  20 \fBlockmail\fR [\-r] [\-t\ \fItimeout\fR] {\fIlockfile\fR} {\fIprogram\fR} [argument...]
  21 .SH "DESCRIPTION"
  22 .PP
  23
  24 \fBlockmail\fR
  25 is a helper utility for working with mailbox files. Mailbox files must be locked to prevent other applications from modifying the mailbox at the same time. Different system use different locking conventions.
  26 \fBlockmail\fR
  27 uses two of the most common locking mechanisms in use, which should work reliably on most systems.
  28 .PP
  29
  30 \fIlockfile\fR
  31 is the pathname to an existing mailbox file. By default,
  32 \fBlockmail\fR
  33 tries to lock the mailbox every five seconds (if the mailbox is already locked), and will give up after three minutes. After the mailbox is succesfully locked,
  34 \fBlockmail\fR
  35 runs
  36 \fIprogram\fR
  37 as a child process, with any optional
  38 \fIargument\fRs. When
  39 \fIprogram\fR
  40 terminates,
  41 \fBlockmail\fR
  42 removes the mailbox lock, and terminates itself.
  43 .SH "OPTIONS"
  44 .PP
  45 \-r
  46 .RS 4
  47 If a regular lock fails, try a read\-only lock. Use this option to lock mailbox files in a read\-only directory.
  48 .RE
  49 .PP
  50 \-t \fItimeout\fR
  51 .RS 4
  52 If the lock attempt fails, try again for up to
  53 \fItimeout\fR
  54 seconds. The actual timeout is rounded up to the next five second interval (a lock attempt is tried every five seconds).
  55 .RE
  56 .SH "DESCRIPTION"
  57 .PP
  58 This section briefly describes the locking mechanism used by
  59 \fBlockmail\fR.
  60 \fBlockmail\fR
  61 uses three different locking conventions in order to maximize compatibility with other mail software: C\-Client folder locks, dot\-locks, and file locks.
  62 .SS "C\-Client folder locks"
  63 .PP
  64 Mail software based on the
  65 C\-Client
  66 library creates lock files named
  67 \fI/tmp/.\fR\fI\fIdddddd\fR\fR\fI.\fR\fI\fIiiiiii\fR\fR. Here,
  68 \fIdddddd\fR
  69 and
  70 \fIiiiiii\fR
  71 are the device number and the inode number of the mailbox file (the
  72 st_dev
  73 and
  74 st_ino
  75 fields in the inode), in hexadecimal. If the process ID saved in the C\-Client folder lock file is not valid,
  76 \fBlockmail\fR
  77 concludes that it's a stale lock file, and will remove it.
  78 .sp
  79 .it 1 an-trap
  80 .nr an-no-space-flag 1
  81 .nr an-break-flag 1
  82 .br
  83 \fBNote\fR
  84 .PP
  85 A race condition exists where a
  86 C\-Client
  87 process is killed after it creates a lock file, but before saving its process ID in the lock file. The race window is very small, but it exists. The
  88 C\-Client
  89 library does not appear to ever clear out the lock file.
  90 .PP
  91
  92 \fBlockmail\fR
  93 attempts to resolve this race condition by deleting zero\-length lock files that are at least five minutes old.
  94 .SS "dot\-locks"
  95 .PP
  96
  97 \fBlockmail\fR
  98 also creates, and honors dot\-lock files. Dot\-lock files are first created as temporary files, then linked to
  99 \fI\fIlockfile\fR\fR\fI.lock\fR. The link operation fails if the dot\-lock file already exists.
 100 \fBlockmail\fR
 101 uses an enhanced method of dot\-locking, where its process ID, and the name of the server where
 102 \fBlockmail\fR
 103 is running is also saved in its dot\-lock file. If the operation fails due to an existing dot\-lock file that was created by another
 104 \fBlockmail\fR
 105 process on the same server, and the process ID no longer exists, this stale dot\-lock file is removed immediately. In all other situations a dot\-lock file older than five minutes is considered stale, and removed.
 106 .sp
 107 .it 1 an-trap
 108 .nr an-no-space-flag 1
 109 .nr an-break-flag 1
 110 .br
 111 \fBNote\fR
 112 .PP
 113 A failure to create a dot\-lock file is silently ignored if the reason for the failure is because
 114 \fBlockmail\fR
 115 does not have the write permission in the dot\-lock file's directory. The incoming mail spool directory (usually
 116 \fI/var/mail\fR) typically does not have global write permissions, so the attempt to create the dot\-lock file in the spool directory will fail, and
 117 \fBlockmail\fR
 118 will be content with using file\-locking only.
 119 .SS "File locks"
 120 .PP
 121 The final locking mechanism
 122 \fBlockmail\fR
 123 uses is the operating system's file locking facility. If
 124 \fBlockmail\fR
 125 fails to obtain all three locks,
 126 \fBlockmail\fR
 127 will sleep for five seconds and try again. The only exception is a failure to create a dot\-lock because of no write access to the dot\-lock file's directory, which is ignored. If
 128 \fBlockmail\fR
 129 still fails to obtain all required locks in the amount of time specified by the
 130 \fB\-t\fR
 131 option (or its default value),
 132 \fBlockmail\fR
 133 will terminate with the
 134 EX_TEMPFAIL
 135 exit code.
 136 .PP
 137
 138 \fBlockmail\fR
 139 runs
 140 \fIprogram\fR
 141 after obtaining the last file lock, waits until
 142 \fIprogram\fR
 143 terminates, and releases all locks.
 144 \fIprogram\fR
 145 must terminate before any of the locks obtained by
 146 \fBlockmail\fR
 147 expire, and are considered stale.
 148 \fBlockmail\fR
 149 will then terminate with the same exit code as
 150 \fIprogram\fR.
 151 .SH "EXIT STATUS"
 152 .PP
 153
 154 \fBlockmail\fR
 155 terminates with the same exit status as
 156 \fIprogram\fR
 157 \fBlockmail\fR
 158 terminates with the
 159 EX_TEMPFAIL
 160 exit status if it was unable to obtain a lock, or if
 161 \fIprogram\fR
 162 was killed by a signal.
 163 .SH "SEE ALSO"
 164 .PP
 165
 166 \fI\fBmaildrop\fR(1)\fR\&[1],
 167 \fBsendmail\fR(8).
 168 .SH "REFERENCES"
 169 .IP " 1." 4
 170 \fBmaildrop\fR(1)
 171 .RS 4
 172 \%maildrop.html
 173 .RE