| 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: 10/09/2025 |
| 8 |
.\" Manual: Double Precision, Inc. |
| 9 |
.\" Source: Courier Mail Server |
| 10 |
.\" Language: English |
| 11 |
.\" |
| 12 |
.TH "LOCKMAIL" "1" "10/09/2025" "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 |
.nr an-no-space-flag 1 |
| 97 |
.nr an-break-flag 1 |
| 98 |
.br |
| 99 |
.ps +1 |
| 100 |
\fBNote\fR |
| 101 |
.ps -1 |
| 102 |
.br |
| 103 |
.PP |
| 104 |
A race condition exists where a |
| 105 |
C\-Client |
| 106 |
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 |
| 107 |
C\-Client |
| 108 |
library does not appear to ever clear out the lock file\&. |
| 109 |
.PP |
| 110 |
\fBlockmail\fR |
| 111 |
attempts to resolve this race condition by deleting zero\-length lock files that are at least five minutes old\&. |
| 112 |
.sp .5v |
| 113 |
.RE |
| 114 |
.SS "dot\-locks" |
| 115 |
.PP |
| 116 |
\fBlockmail\fR |
| 117 |
also creates, and honors dot\-lock files\&. Dot\-lock files are first created as temporary files, then linked to |
| 118 |
\fIlockfile\fR\&.lock\&. The link operation fails if the dot\-lock file already exists\&. |
| 119 |
\fBlockmail\fR |
| 120 |
uses an enhanced method of dot\-locking, where its process ID, and the name of the server where |
| 121 |
\fBlockmail\fR |
| 122 |
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 |
| 123 |
\fBlockmail\fR |
| 124 |
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\&. |
| 125 |
.if n \{\ |
| 126 |
.sp |
| 127 |
.\} |
| 128 |
.RS 4 |
| 129 |
.nr an-no-space-flag 1 |
| 130 |
.nr an-break-flag 1 |
| 131 |
.br |
| 132 |
.ps +1 |
| 133 |
\fBNote\fR |
| 134 |
.ps -1 |
| 135 |
.br |
| 136 |
.PP |
| 137 |
A failure to create a dot\-lock file is silently ignored if the reason for the failure is because |
| 138 |
\fBlockmail\fR |
| 139 |
does not have the write permission in the dot\-lock file\*(Aqs directory\&. The incoming mail spool directory (usually |
| 140 |
/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 |
| 141 |
\fBlockmail\fR |
| 142 |
will be content with using file\-locking only\&. |
| 143 |
.sp .5v |
| 144 |
.RE |
| 145 |
.SS "File locks" |
| 146 |
.PP |
| 147 |
The final locking mechanism |
| 148 |
\fBlockmail\fR |
| 149 |
uses is the operating system\*(Aqs file locking facility\&. If |
| 150 |
\fBlockmail\fR |
| 151 |
fails to obtain all three locks, |
| 152 |
\fBlockmail\fR |
| 153 |
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 |
| 154 |
\fBlockmail\fR |
| 155 |
still fails to obtain all required locks in the amount of time specified by the |
| 156 |
\fB\-t\fR |
| 157 |
option (or its default value), |
| 158 |
\fBlockmail\fR |
| 159 |
will terminate with the |
| 160 |
EX_TEMPFAIL |
| 161 |
exit code\&. |
| 162 |
.PP |
| 163 |
\fBlockmail\fR |
| 164 |
runs |
| 165 |
\fIprogram\fR |
| 166 |
after obtaining the last file lock, waits until |
| 167 |
\fIprogram\fR |
| 168 |
terminates, and releases all locks\&. |
| 169 |
\fIprogram\fR |
| 170 |
must terminate before any of the locks obtained by |
| 171 |
\fBlockmail\fR |
| 172 |
expire, and are considered stale\&. |
| 173 |
\fBlockmail\fR |
| 174 |
will then terminate with the same exit code as |
| 175 |
\fIprogram\fR\&. |
| 176 |
.SH "EXIT STATUS" |
| 177 |
.PP |
| 178 |
\fBlockmail\fR |
| 179 |
terminates with the same exit status as |
| 180 |
\fIprogram\fR |
| 181 |
\fBlockmail\fR |
| 182 |
terminates with the |
| 183 |
EX_TEMPFAIL |
| 184 |
exit status if it was unable to obtain a lock, or if |
| 185 |
\fIprogram\fR |
| 186 |
was killed by a signal\&. |
| 187 |
.SH "SEE ALSO" |
| 188 |
.PP |
| 189 |
\m[blue]\fB\fBmaildrop\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2, |
| 190 |
\fBsendmail\fR(8)\&. |
| 191 |
.SH "AUTHOR" |
| 192 |
.PP |
| 193 |
\fBSam Varshavchik\fR |
| 194 |
.RS 4 |
| 195 |
Author |
| 196 |
.RE |
| 197 |
.SH "NOTES" |
| 198 |
.IP " 1." 4 |
| 199 |
\fBmaildrop\fR(1) |
| 200 |
.RS 4 |
| 201 |
\%http://www.courier-mta.org/maildrop.html |
| 202 |
.RE |