.\"                                      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).