NAME

       lockfile-progs - command-line programs to safely lock and unlock files and mailboxes (via liblockfile).

SYNOPSIS

       mail-lock [--use-pid] [--retry retry-count]
       mail-unlock
       mail-touchlock [--oneshot]

       lockfile-create [--use-pid] [--retry retry-count] [--lock-name] filename
       lockfile-remove [--lock-name] filename
       lockfile-touch [--oneshot] [--lock-name] filename
       lockfile-check [--use-pid] [--lock-name] filename

DESCRIPTION

       Lockfile-progs  provides  a set a programs that can be used to lock and unlock mailboxes and files safely
       (via liblockfile):

           mail-lock - lock the current user's mailbox
           mail-unlock - unlock the current user's mailbox
           mail-touchlock - touch the lock on the current user's mailbox

           lockfile-create - lock a given file
           lockfile-remove - remove the lock on a given file
           lockfile-touch - touch the lock on a given file
           lockfile-check - check the lock on a given file

       By default, the filename argument refers to the name of the file to  be  locked,  and  the  name  of  the
       lockfile  will  be filename .lock.  However, if the --lock-name argument is specified, then filename will
       be taken as the name of the lockfile itself.

       Each of the mail locking commands attempts to lock  /var/spool/mail/<user>,  where  <user>  is  the  name
       associated with the effective user ID, as determined by via geteuid(2).

       Once  a  file  is  locked,  the lock must be touched at least once every five minutes or the lock will be
       considered stale, and subsequent lock attempts will succeed.  Also  see  the  --use-pid  option  and  the
       lockfile_create(3) manpage.

       The lockfile-check command tests whether or not a valid lock already exists.

OPTIONS

       -q, --quiet
           Suppress any output.  Success or failure will only be indicated by the exit status.

       -v, --verbose
           Enable diagnostic output.

       -l, --lock-name
           Do  not  append  .lock  to  the  filename.   This option applies to lockfile-create, lockfile-remove,
           lockfile-touch, or lockfile-check.

       -p, --use-pid
           Write the parent process id (PPID) to the lockfile whenever a lockfile is created, and use  that  pid
           when  checking  a  lock's  validity.   See the lockfile_create(3) manpage for more information.  This
           option applies to lockfile-create and lockfile-check.  NOTE: this  option  will  not  work  correctly
           between machines sharing a filesystem.

       -o, --oneshot
           Touch the lock and exit immediately.  This option applies to lockfile-touch and mail-touchlock.  When
           not provided, these commands will run forever, touching the lock once every minute until killed.

       -r retry-count, --retry retry-count
           Try to lock filename retry-count times before giving up.  Each attempt will be delayed a  bit  longer
           than  the last (in 5 second increments) until reaching a maximum delay of one minute between retries.
           If retry-count is unspecified, the default is 9 which will give up after 180 seconds (3  minutes)  if
           all 9 lock attempts fail.

EXAMPLES

       Locking a file during a lengthy process:

         lockfile-create /some/file
         lockfile-touch /some/file &
         # Save the PID of the lockfile-touch process
         BADGER="$!"
         do-something-important-with /some/file
         kill "${BADGER}"
         lockfile-remove /some/file

EXIT STATUS

       0
           For  lockfile-check  this  indicates that a valid lock exists, otherwise it just indicates successful
           program execution.

       Not 0
           For lockfile-check a non-zero exit status indicates that the specified lock does not exist or is  not
           valid.  For other programs it indicates that some problem was encountered.

SEE ALSO

       maillock(3)
       touchlock(3)
       mailunlock(3)
       lockfile_create(3)
       lockfile_remove(3)
       lockfile_touch(3)
       lockfile_check(3)

AUTHOR

       Written by Rob Browning <rlb@defaultvalue.org>