--- /dev/null
+'\" 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
HCoop / hcoop / debian / courier-authlib.git / blobdiff