1 files changed, 153 insertions, 0 deletions
diff --git a/debian/manpages/exim_lock.8 b/debian/manpages/exim_lock.8
new file mode 100644
index 0000000..3d8833b
--- /dev/null
+++ b/debian/manpages/exim_lock.8
@@ -0,0 +1,153 @@
+.\"                                      Hey, EMACS: -*- nroff -*-
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH EXIM_LOCK 8 "May 12, 2020"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh        disable hyphenation
+.\" .hy        enable hyphenation
+.\" .ad l      left justify
+.\" .ad b      justify to both left and right margins
+.\" .nf        disable filling
+.\" .fi        enable filling
+.\" .br        insert line break
+.\" .sp <n>    insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.\" \(oqthis text is enclosed in single quotes\(cq
+.\" \(lqthis text is enclosed in double quotes\(rq
+.SH NAME
+exim_lock \- Mailbox maintenance
+.SH SYNOPSIS
+.B exim_lock
+.RI [ options ] mailbox-file
+
+.SH DESCRIPTION
+The
+.B exim_lock
+utility locks a mailbox file using the same algorithm as Exim.
+For a discussion of locking issues, see section "appendfile transport",
+subsection "Operational details for appending" the Exim specification.
+.B exim_lock
+can be used to prevent any modification of a mailbox by Exim or a user
+agent while investigating a problem.
+The utility requires the name of the file as its first argument.
+If the locking is successful, the second argument is run as a command
+(using C's \(lqsystem()\(rq function); if there is no second argument, the value
+of the SHELL environment variable is used; if this is unset or empty,
+/bin/sh is run.
+When the command finishes, the mailbox is unlocked and the utility ends.
+The following options are available:
+.TP
+.I \-fcntl
+Use \(lqfcntl()\(rq locking on the open mailbox.
+.TP
+.I \-flock
+Use \(lqflock()\(rq locking on the open mailbox, provided the operating
+system supports it.
+.TP
+.I \-interval
+This must be followed by a number, which is a number of seconds; it
+sets the interval to sleep between retries (default 3).
+.TP
+.I \-lockfile
+Create a lock file before opening the mailbox.
+.TP
+.I \-mbx
+Lock the mailbox using MBX rules.
+.TP
+.I \-q
+Suppress verification output.
+.TP
+.I \-retries
+This must be followed by a number; it sets the number of times to try
+to get the lock (default 10).
+.TP
+.I \-restore_time
+This option causes exim_lock to restore the modified and read times to the
+locked file before exiting. This allows you to access a locked mailbox (for
+example, to take a backup copy) without disturbing the times that the user
+subsequently sees.
+.TP
+.I \-timeout
+This must be followed by a number, which is a number of seconds; it
+sets a timeout to be used with a blocking \(lqfcntl()\(rq lock.
+If it is not set (the default), a non-blocking call is used.
+.TP
+.I \-v
+Generate verbose output.
+
+If none of
+.I \-fcntl, \-flock, \-lockfile
+or
+.I \-mbx
+are given, the default is to create a lock file and also use \(lqfcntl()\(rq
+locking on the mailbox, which is the same as
+.B Exim's
+default.
+The use of
+.I \-fcntl
+or
+.I \-flock
+requires that the file be writable; the use of
+.I \-lockfile
+requires that the directory containing the file be writable.
+Locking by lock file does not last for ever; Exim assumes that a lock file
+is expired if it is more than 30 minutes old.
+
+The
+.I \-mbx
+can be used with either or both of
+.I \-fcntl
+or
+.I \-flock.
+It assumes
+.I \-fcntl
+by default. MBX locking causes a shared lock to be taken out on the open
+mailbox, and an exclusive lock on the file /tmp/.n.m where n and m are the
+device number and inode number of the mailbox file. When the locking is
+released, if an exclusive lock can be obtained for the mailbox, the file
+in /tmp is deleted.
+
+The default output contains verification of the locking that takes place.
+The
+.I \-v
+option causes some additional information to be given.
+The
+.I \-q
+option suppresses all output except error messages.
+.PP
+A command such as
+
+  exim_lock /var/spool/mail/spqr
+
+runs an interactive shell while the file is locked, whereas
+
+  exim_lock \-q /var/spool/mail/spqr <<End
+  <some commands>
+  End
+
+runs a specific non-interactive sequence of commands while the file is
+locked, suppressing all verification output.
+A single command can be run by a command such as
+
+  exim_lock \-q /var/spool/mail/spqr \
+    "cp /var/spool/mail/spqr /some/where"
+
+Note that if a command is supplied, it must be entirely contained within
+the second argument - hence the quotes.
+
+.SH BUGS
+This manual page needs a major re-work. If somebody knows better groff
+than us and has more experience in writing manual pages, any patches
+would be greatly appreciated.
+
+.SH SEE ALSO
+.BR exim (8),
+/usr/share/doc/exim4\-base/
+
+.SH AUTHOR
+This manual page was stitched together from spec.txt by
+Andreas Metzler <ametzler at downhill.at.eu.org>,
+for the Debian GNU/Linux system (but may be used by others).