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 arguments.
       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)[1], sendmail(8).

AUTHOR

       Sam Varshavchik
           Author

NOTES

        1. maildrop(1)
           http://www.courier-mta.org/maildrop.html