+++ /dev/null
-.\" <!-- $Id: lockmail.sgml,v 1.8 2007/04/22 15:05:16 mrsam Exp $ -->
-.\" <!-- Copyright 2002-2007 Double Precision, Inc. See COPYING for -->
-.\" <!-- distribution information. -->
-.\" Title: lockmail
-.\" Author:
-.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
-.\" Date: 08/23/2008
-.\" Manual: Double Precision, Inc.
-.\" Source: Double Precision, Inc.
-.\"
-.TH "LOCKMAIL" "1" "08/23/2008" "Double Precision, Inc." "Double Precision, Inc."
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.SH "NAME"
-lockmail - create mail lock files
-.SH "SYNOPSIS"
-.HP 9
-\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 succesfully 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
-\fI/tmp/\.\fR\fI\fIdddddd\fR\fR\fI\.\fR\fI\fIiiiiii\fR\fR\. Here,
-\fIdddddd\fR
-and
-\fIiiiiii\fR
-are the device number and the inode number of the mailbox file (the
-st_dev
-and
-st_ino
-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\'s a stale lock file, and will remove it\.
-.sp
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br
-Note
-.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\.
-.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
-\fI\fIlockfile\fR\fR\fI\.lock\fR\. 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\.
-.sp
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br
-Note
-.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\'s directory\. The incoming mail spool directory (usually
-\fI/var/mail\fR) 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\.
-.SS "File locks"
-.PP
-The final locking mechanism
-\fBlockmail\fR
-uses is the operating system\'s 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\'s 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
-
-\fI\fBmaildrop\fR(1)\fR\&[1],
-\fBsendmail\fR(8)\.
-.SH "NOTES"
-.IP " 1." 4
-\fBmaildrop\fR(1)
-.RS 4
-\%maildrop.html
-.RE
HCoop / hcoop / debian / courier-authlib.git / blobdiff