Man Linux: Main Page and Category List

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  current  process  id  (PID)  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, lockfile-remove,  lockfile-
           touch, and lockfile-check.

       -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>