---
name: "lockmail.courier"
section: "1"
platform: "linux"
package: "courier-mta"
version: "1.4.1-3+deb13u2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/lockmail.courier"
---

# lockmail.courier(1)

create mail lock files

## NAME

lockmail - create mail lock files

## SYNOPSIS

**lockmail** \[-r\] \[-t *timeout*\] {*lockfile*} {*program*} \[argument...\]

## DESCRIPTION

**lockmail** 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. **lockmail** uses two of the most common locking mechanisms in use, which should work reliably on most systems.

*lockfile* is the pathname to an existing mailbox file. By default, **lockmail** 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 successfully locked, **lockmail** runs *program* as a child process, with any optional *argument*s. When *program* terminates, **lockmail** removes the mailbox lock, and terminates itself.

## OPTIONS

- \-r

  If a regular lock fails, try a read-only lock. Use this option to lock mailbox files in a read-only directory.

- \-t *timeout*

  If the lock attempt fails, try again for up to *timeout* seconds. The actual timeout is rounded up to the next five second interval (a lock attempt is tried every five seconds).

## DESCRIPTION

This section briefly describes the locking mechanism used by **lockmail**. **lockmail** uses three different locking conventions in order to maximize compatibility with other mail software: C-Client folder locks, dot-locks, and file locks.

### C-Client folder locks

Mail software based on the C-Client library creates lock files named /tmp/.*dddddd*.*iiiiii*. Here, *dddddd* and *iiiiii* 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, **lockmail** concludes that it's a stale lock file, and will remove it.

**Note**\

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.

**lockmail** attempts to resolve this race condition by deleting zero-length lock files that are at least five minutes old.

### dot-locks

**lockmail** also creates, and honors dot-lock files. Dot-lock files are first created as temporary files, then linked to *lockfile*.lock. The link operation fails if the dot-lock file already exists. **lockmail** uses an enhanced method of dot-locking, where its process ID, and the name of the server where **lockmail** 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 **lockmail** 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.

**Note**\

A failure to create a dot-lock file is silently ignored if the reason for the failure is because **lockmail** does not have the write permission in the dot-lock file's directory. The incoming mail spool directory (usually /var/mail) typically does not have global write permissions, so the attempt to create the dot-lock file in the spool directory will fail, and **lockmail** will be content with using file-locking only.

### File locks

The final locking mechanism **lockmail** uses is the operating system's file locking facility. If **lockmail** fails to obtain all three locks, **lockmail** 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 **lockmail** still fails to obtain all required locks in the amount of time specified by the **-t** option (or its default value), **lockmail** will terminate with the EX\_TEMPFAIL exit code.

**lockmail** runs *program* after obtaining the last file lock, waits until *program* terminates, and releases all locks. *program* must terminate before any of the locks obtained by **lockmail** expire, and are considered stale. **lockmail** will then terminate with the same exit code as *program*.

## EXIT STATUS

**lockmail** terminates with the same exit status as *program* **lockmail** terminates with the EX\_TEMPFAIL exit status if it was unable to obtain a lock, or if *program* was killed by a signal.

## SEE ALSO

[**maildrop**(1)](/maildrop/1.md)\[1\], [**sendmail**(8)](/sendmail/8.md).

## AUTHOR

**Sam Varshavchik**

Author

## NOTES

- 1\.

  [**maildrop**(1)](/maildrop/1.md)

  http://www.courier-mta.org/maildrop.html