Merge branch 'debian'

[hcoop/debian/courier-authlib.git] / libs / liblock / lockmail.1

'\" t
.\"<!-- Copyright 2002-2007 Double Precision, Inc.  See COPYING for -->
.\"<!-- distribution information. -->
.\"     Title: lockmail
.\"    Author: Sam Varshavchik
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 08/25/2013
.\"    Manual: Double Precision, Inc.
.\"    Source: Courier Mail Server
.\"  Language: English
.\"
.TH "LOCKMAIL" "1" "08/25/2013" "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
\%[set $man.base.url.for.relative.links]/maildrop.html
.RE