#### 3.2.10 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.20, 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`.