GNU Mailutils
	General-Purpose Mail Package	Official GNU Software

• Main
• Downloads
• Documentation
• Wiki

3.2.9 The locking Statement

Syntax

locking {
  # Default locker flags.
  type default | dotlock | external | kernel | null;
  
  # Set the maximum number of times to retry acquiring the lock.
  retry-count number;
  
  # Set the delay between two successive locking attempts.
  retry-sleep arg;
  
  # Expire locks older than this amount of time.
  expire-timeout number;

  # Check if PID of the lock owner is active, steal the lock if it not. 
  pid-check bool;

  # Use prog as external locker program.
  external-locker prog;
}

Description

This compound statement configures various parameters used when locking UNIX mailboxes in order to prevent simultaneous writes.

It is important to note, that locking applies only to monolithic mailboxes, i.e. mailboxes of ‘mbox’ and ‘dotmail’ types (see mbox). Other mailbox types don’t require locking.

Configuration: type string

Set locking type. Allowed arguments are:

default

Default locking type. As of mailutils version 3.14, this is equivalent to dotlock.

dotlock

A ‘dotlock’-style locking. To lock a mailbox named X a lock file named X.lock is created. If pid-check yes is set, this file will contain the PID of the locking process, so that another process wishing to acquire the lock could verify if the lock is still in use.

external

Run external program to perform locking/unlocking operations. The name of the program is given by the external-locker statement (see below). If it is not given, the built-in default ‘dotlock’ is used.

The locker program is invoked as follows:

# To lock mbox:
locker -fexpire_timeout -rretry_count mbox
# To unlock it:
locker -u -fexpire_timeout -rretry_count mbox

Here, expire_timeout is the value supplied with the expire-timeout configuration statement, and retry_count is the value supplied with the retry-count statement (see below).

To properly interact with mailutils, the external locker program must use the following exit codes:

Exit code	Meaning
0	Success.
1	Failed due to an error.
2	Unlock requested (-u), but file is not locked.
3	Lock requested, but file is already locked.
4	Insufficient permissions.

See dotlock, for the description of the default external locker, shipped with mailutils.

kernel

Use kernel locking mechanism (fcntl(2)).

null

No locking at all. The statements below are silently ignored.

Configuration: retry-count number

Number of locking attempts. The default is 10.

Configuration: retry-sleep seconds

Configuration: retry-timeout seconds

Time interval, in seconds, between two successive locking attempts. The default is 1 second. The retry-timeout statement is deprecated because of its misleading name.

Configuration: expire-timeout seconds

Sets the expiration timeout. The existing lock file will be removed, if it was created more than this number of seconds ago. The default is 600.

Configuration: pid-check bool

This statement can be used if locking type is set to dotlock. If set to true, it instructs the locking algorithm to check if the PID of the lock owner is still running by the time when it tries to acquire the lock. This works as follows. When the lock file is created, the PID of the creating process is written to it. If another process tries to acquire the lock and sees that the lock file already exists, it reads the PID from the file and checks if a process with that PID still exists in the process table. If it does not, the process considers the lock file to be stale, removes it and locks the mailbox.

Configuration: external-locker string

Sets the name of the external locker program to use, instead of the default ‘dotlock’.

This statement is in effect only when used together with type external.