'\" t .\" .\" .\" Title: lockmail .\" Author: Sam Varshavchik .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 10/28/2020 .\" Manual: Double Precision, Inc. .\" Source: Courier Mail Server .\" Language: English .\" .TH "LOCKMAIL" "1" "10/28/2020" "Courier Mail Server" "Double Precision, Inc\&." .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" lockmail \- create mail lock files .SH "SYNOPSIS" .HP \w'\fBlockmail\fR\ 'u \fBlockmail\fR [\-r] [\-t\ \fItimeout\fR] {\fIlockfile\fR} {\fIprogram\fR} [argument...] .SH "DESCRIPTION" .PP \fBlockmail\fR 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\&. \fBlockmail\fR uses two of the most common locking mechanisms in use, which should work reliably on most systems\&. .PP \fIlockfile\fR is the pathname to an existing mailbox file\&. By default, \fBlockmail\fR 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, \fBlockmail\fR runs \fIprogram\fR as a child process, with any optional \fIargument\fRs\&. When \fIprogram\fR terminates, \fBlockmail\fR removes the mailbox lock, and terminates itself\&. .SH "OPTIONS" .PP \-r .RS 4 If a regular lock fails, try a read\-only lock\&. Use this option to lock mailbox files in a read\-only directory\&. .RE .PP \-t \fItimeout\fR .RS 4 If the lock attempt fails, try again for up to \fItimeout\fR seconds\&. The actual timeout is rounded up to the next five second interval (a lock attempt is tried every five seconds)\&. .RE .SH "DESCRIPTION" .PP This section briefly describes the locking mechanism used by \fBlockmail\fR\&. \fBlockmail\fR uses three different locking conventions in order to maximize compatibility with other mail software: C\-Client folder locks, dot\-locks, and file locks\&. .SS "C\-Client folder locks" .PP Mail software based on the C\-Client library creates lock files named /tmp/\&.\fIdddddd\fR\&.\fIiiiiii\fR\&. Here, \fIdddddd\fR and \fIiiiiii\fR are the device number and the inode number of the mailbox file (the \fIst_dev\fR and \fIst_ino\fR fields in the inode), in hexadecimal\&. If the process ID saved in the C\-Client folder lock file is not valid, \fBlockmail\fR concludes that it\*(Aqs a stale lock file, and will remove it\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP A race condition exists where a C\-Client 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 C\-Client library does not appear to ever clear out the lock file\&. .PP \fBlockmail\fR attempts to resolve this race condition by deleting zero\-length lock files that are at least five minutes old\&. .sp .5v .RE .SS "dot\-locks" .PP \fBlockmail\fR also creates, and honors dot\-lock files\&. Dot\-lock files are first created as temporary files, then linked to \fIlockfile\fR\&.lock\&. The link operation fails if the dot\-lock file already exists\&. \fBlockmail\fR uses an enhanced method of dot\-locking, where its process ID, and the name of the server where \fBlockmail\fR 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 \fBlockmail\fR 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\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP A failure to create a dot\-lock file is silently ignored if the reason for the failure is because \fBlockmail\fR does not have the write permission in the dot\-lock file\*(Aqs directory\&. The incoming mail spool directory (usually /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 \fBlockmail\fR will be content with using file\-locking only\&. .sp .5v .RE .SS "File locks" .PP The final locking mechanism \fBlockmail\fR uses is the operating system\*(Aqs file locking facility\&. If \fBlockmail\fR fails to obtain all three locks, \fBlockmail\fR 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 \fBlockmail\fR still fails to obtain all required locks in the amount of time specified by the \fB\-t\fR option (or its default value), \fBlockmail\fR will terminate with the EX_TEMPFAIL exit code\&. .PP \fBlockmail\fR runs \fIprogram\fR after obtaining the last file lock, waits until \fIprogram\fR terminates, and releases all locks\&. \fIprogram\fR must terminate before any of the locks obtained by \fBlockmail\fR expire, and are considered stale\&. \fBlockmail\fR will then terminate with the same exit code as \fIprogram\fR\&. .SH "EXIT STATUS" .PP \fBlockmail\fR terminates with the same exit status as \fIprogram\fR \fBlockmail\fR terminates with the EX_TEMPFAIL exit status if it was unable to obtain a lock, or if \fIprogram\fR was killed by a signal\&. .SH "SEE ALSO" .PP \m[blue]\fB\fBmaildrop\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2, \fBsendmail\fR(8)\&. .SH "AUTHOR" .PP \fBSam Varshavchik\fR .RS 4 Author .RE .SH "NOTES" .IP " 1." 4 \fBmaildrop\fR(1) .RS 4 \%http://www.courier-mta.org/maildrop.html .RE