dotlockfile

DOTLOCKFILE(1)                 Cistron Utilities                DOTLOCKFILE(1)

NAME
       dotlockfile - Utility to manage lockfiles

SYNOPSIS
       dotlockfile -l [-r retries] [-p] <-m | lockfile>
       dotlockfile -l [-r retries] [-p] <-m | lockfile> cmd args ...
       dotlockfile -u | -t

DESCRIPTION
       dotlockfile  is a command line utility to reliably create, test and re-
       move lockfiles.   It  creates  lockfiles  reliably  on  local  and  NFS
       filesystems,  because  the  crucial  steps of testing for a preexisting
       lockfile and creating it are performed atomically by a single  call  to
       link(2).  Manpage lockfile_create(3) describes the used algorithm.

       dotlockfile  is  installed with attribute SETGID mail and thus can also
       be used to lock and unlock mailboxes even if the mailspool directory is
       only writable by group mail.

       The  name  dotlockfile  comes from the way mailboxes are locked for up-
       dates on a lot of UNIX systems.  A lockfile is created  with  the  same
       filename as the mailbox but with the string ".lock" appended.

       The names dotlock and lockfile were already taken - hence the name dot-
       lockfile :).

OPTIONS
       -l     Create a lockfile if no preexisting  valid  lockfile  is  found,
              else  wait and retry according to option -r.  This option is the
              default, so it can be left off.

              A lockfile is treated as valid,
              o  if it holds the process-id of a running process,
              o  or if it does not hold any process-id and  has  been  touched
              less than 5 minutes ago (timestamp is younger than 5 minutes).

       -r retries
              The  number  of times dotlockfile retries to acquire the lock if
              it failed the first time before giving up.   The  initial  sleep
              after  failing  to  acquire  the  lock is 5 seconds.  After each
              retry the sleep interval is increased incrementally by 5 seconds
              up  to a maximum sleep of 60 seconds between tries.  The default
              number of retries is 5.  To try only once, use "-r 0".   To  try
              indefinitely, use "-r -1".

       -u     Remove a lockfile.

       -t     Touch  an  existing lockfile (update the timestamp).  Useful for
              lockfiles on NFS filesystems.  For lockfiles on  local  filesys-
              tems the -p option is preferable.

       -p     Write  the process-id of the calling process (or dotlockfile it-
              self if a command is executed) into  the  lockfile.   Also  when
              testing  for  an  existing  lockfile, check the contents for the
              process-id of a running process to verify  if  the  lockfile  is
              still  valid.   Obviously  useful  only  for  lockfiles on local
              filesystems.

       -m     Lock or unlock the current users mailbox.  The path to the mail-
              box   is   the   default  system  mailspool  directory  (usually
              /var/mail) with the username as gotten from getpwuid() appended.
              If  the environment variable $MAIL is set, that is used instead.
              Then the string ".lock" is appended to get the name of  the  ac-
              tual lockfile.

       lockfile
              The lockfile to be created or removed.  Must not be specified if
              the -m option is given.

       command argument ...
              Create lockfile, run the command , wait for it to exit, and  re-
              move lockfile.

RETURN VALUE
       Zero  on  success, and non-zero on failure.  When locking (the default,
       or with the -l option) dotlockfile returns the same values as  the  li-
       brary  function  lockfile_create(3).  Unlocking a non-existent lockfile
       is not an error.

       If a command is executed, the return value  does  not  correspond  with
       that  of  the  command  that was run.  If the locking and unlocking was
       successful, the exit status is always zero.

NOTES
       The lockfile is created exactly as named on the command line.  The  ex-
       tension ".lock" is not automatically appended.

       This  utility is a lot like the lockfile(1) utility included with proc-
       mail, and the mutt_dotlock(1) utility included with mutt.  However  the
       command-line  arguments  differ,  and so does the return status.  It is
       believed, that dotlockfile is the most flexible  implementation,  since
       it  automatically  detects  when  it  needs to use privileges to lock a
       mailbox, and does it safely.

       The above mentioned lockfile_create(3) manpage is present  in  the  li-
       blockfile-dev package.

BUGS
       None known.

SEE ALSO
       lockfile_create(3), maillock(3)

AUTHOR
       Miquel van Smoorenburg, miquels@cistron.nl

                               January 10, 2017                 DOTLOCKFILE(1)