libs/liblock/lockmail.1

   1 '\" t
   2 .\"<!-- Copyright 2002-2007 Double Precision, Inc.  See COPYING for -->
   3 .\"<!-- distribution information. -->
   4 .\"     Title: lockmail
   5 .\"    Author: Sam Varshavchik
   6 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   7 .\"      Date: 09/08/2017
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Courier Mail Server
  10 .\"  Language: English
  11 .\"
  12 .TH "LOCKMAIL" "1" "09/08/2017" "Courier Mail Server" "Double Precision, Inc\&."
  13 .\" -----------------------------------------------------------------
  14 .\" * Define some portability stuff
  15 .\" -----------------------------------------------------------------
  16 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  17 .\" http://bugs.debian.org/507673
  18 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  19 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  20 .ie \n(.g .ds Aq \(aq
  21 .el       .ds Aq '
  22 .\" -----------------------------------------------------------------
  23 .\" * set default formatting
  24 .\" -----------------------------------------------------------------
  25 .\" disable hyphenation
  26 .nh
  27 .\" disable justification (adjust text to left margin only)
  28 .ad l
  29 .\" -----------------------------------------------------------------
  30 .\" * MAIN CONTENT STARTS HERE *
  31 .\" -----------------------------------------------------------------
  32 .SH "NAME"
  33 lockmail \- create mail lock files
  34 .SH "SYNOPSIS"
  35 .HP \w'\fBlockmail\fR\ 'u
  36 \fBlockmail\fR [\-r] [\-t\ \fItimeout\fR] {\fIlockfile\fR} {\fIprogram\fR} [argument...]
  37 .SH "DESCRIPTION"
  38 .PP
  39 \fBlockmail\fR
  40 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\&.
  41 \fBlockmail\fR
  42 uses two of the most common locking mechanisms in use, which should work reliably on most systems\&.
  43 .PP
  44 \fIlockfile\fR
  45 is the pathname to an existing mailbox file\&. By default,
  46 \fBlockmail\fR
  47 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 successfully locked,
  48 \fBlockmail\fR
  49 runs
  50 \fIprogram\fR
  51 as a child process, with any optional
  52 \fIargument\fRs\&. When
  53 \fIprogram\fR
  54 terminates,
  55 \fBlockmail\fR
  56 removes the mailbox lock, and terminates itself\&.
  57 .SH "OPTIONS"
  58 .PP
  59 \-r
  60 .RS 4
  61 If a regular lock fails, try a read\-only lock\&. Use this option to lock mailbox files in a read\-only directory\&.
  62 .RE
  63 .PP
  64 \-t \fItimeout\fR
  65 .RS 4
  66 If the lock attempt fails, try again for up to
  67 \fItimeout\fR
  68 seconds\&. The actual timeout is rounded up to the next five second interval (a lock attempt is tried every five seconds)\&.
  69 .RE
  70 .SH "DESCRIPTION"
  71 .PP
  72 This section briefly describes the locking mechanism used by
  73 \fBlockmail\fR\&.
  74 \fBlockmail\fR
  75 uses three different locking conventions in order to maximize compatibility with other mail software: C\-Client folder locks, dot\-locks, and file locks\&.
  76 .SS "C\-Client folder locks"
  77 .PP
  78 Mail software based on the
  79 C\-Client
  80 library creates lock files named
  81 /tmp/\&.\fIdddddd\fR\&.\fIiiiiii\fR\&. Here,
  82 \fIdddddd\fR
  83 and
  84 \fIiiiiii\fR
  85 are the device number and the inode number of the mailbox file (the
  86 \fIst_dev\fR
  87 and
  88 \fIst_ino\fR
  89 fields in the inode), in hexadecimal\&. If the process ID saved in the C\-Client folder lock file is not valid,
  90 \fBlockmail\fR
  91 concludes that it\*(Aqs a stale lock file, and will remove it\&.
  92 .if n \{\
  93 .sp
  94 .\}
  95 .RS 4
  96 .it 1 an-trap
  97 .nr an-no-space-flag 1
  98 .nr an-break-flag 1
  99 .br
 100 .ps +1
 101 \fBNote\fR
 102 .ps -1
 103 .br
 104 .PP
 105 A race condition exists where a
 106 C\-Client
 107 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
 108 C\-Client
 109 library does not appear to ever clear out the lock file\&.
 110 .PP
 111 \fBlockmail\fR
 112 attempts to resolve this race condition by deleting zero\-length lock files that are at least five minutes old\&.
 113 .sp .5v
 114 .RE
 115 .SS "dot\-locks"
 116 .PP
 117 \fBlockmail\fR
 118 also creates, and honors dot\-lock files\&. Dot\-lock files are first created as temporary files, then linked to
 119 \fIlockfile\fR\&.lock\&. The link operation fails if the dot\-lock file already exists\&.
 120 \fBlockmail\fR
 121 uses an enhanced method of dot\-locking, where its process ID, and the name of the server where
 122 \fBlockmail\fR
 123 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
 124 \fBlockmail\fR
 125 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\&.
 126 .if n \{\
 127 .sp
 128 .\}
 129 .RS 4
 130 .it 1 an-trap
 131 .nr an-no-space-flag 1
 132 .nr an-break-flag 1
 133 .br
 134 .ps +1
 135 \fBNote\fR
 136 .ps -1
 137 .br
 138 .PP
 139 A failure to create a dot\-lock file is silently ignored if the reason for the failure is because
 140 \fBlockmail\fR
 141 does not have the write permission in the dot\-lock file\*(Aqs directory\&. The incoming mail spool directory (usually
 142 /var/mail) typically does not have global write permissions, so the attempt to create the dot\-lock file in the spool directory will fail, and
 143 \fBlockmail\fR
 144 will be content with using file\-locking only\&.
 145 .sp .5v
 146 .RE
 147 .SS "File locks"
 148 .PP
 149 The final locking mechanism
 150 \fBlockmail\fR
 151 uses is the operating system\*(Aqs file locking facility\&. If
 152 \fBlockmail\fR
 153 fails to obtain all three locks,
 154 \fBlockmail\fR
 155 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\*(Aqs directory, which is ignored\&. If
 156 \fBlockmail\fR
 157 still fails to obtain all required locks in the amount of time specified by the
 158 \fB\-t\fR
 159 option (or its default value),
 160 \fBlockmail\fR
 161 will terminate with the
 162 EX_TEMPFAIL
 163 exit code\&.
 164 .PP
 165 \fBlockmail\fR
 166 runs
 167 \fIprogram\fR
 168 after obtaining the last file lock, waits until
 169 \fIprogram\fR
 170 terminates, and releases all locks\&.
 171 \fIprogram\fR
 172 must terminate before any of the locks obtained by
 173 \fBlockmail\fR
 174 expire, and are considered stale\&.
 175 \fBlockmail\fR
 176 will then terminate with the same exit code as
 177 \fIprogram\fR\&.
 178 .SH "EXIT STATUS"
 179 .PP
 180 \fBlockmail\fR
 181 terminates with the same exit status as
 182 \fIprogram\fR
 183 \fBlockmail\fR
 184 terminates with the
 185 EX_TEMPFAIL
 186 exit status if it was unable to obtain a lock, or if
 187 \fIprogram\fR
 188 was killed by a signal\&.
 189 .SH "SEE ALSO"
 190 .PP
 191 \m[blue]\fB\fBmaildrop\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2,
 192 \fBsendmail\fR(8)\&.
 193 .SH "AUTHOR"
 194 .PP
 195 \fBSam Varshavchik\fR
 196 .RS 4
 197 Author
 198 .RE
 199 .SH "NOTES"
 200 .IP " 1." 4
 201 \fBmaildrop\fR(1)
 202 .RS 4
 203 \%http://www.courier-mta.org/maildrop.html
 204 .RE