# DOTLOCKFILE - Utility to manage lockfiles - man(1) - [phpMan]

[_DOTLOCKFILE_(1)](https://www.chedong.com/phpMan.php/man/DOTLOCKFILE/1/markdown)                            Cistron Utilities                           [_DOTLOCKFILE_(1)](https://www.chedong.com/phpMan.php/man/DOTLOCKFILE/1/markdown)

## NAME
       dotlockfile - Utility to manage lockfiles

## SYNOPSIS
       **dotlockfile -l **[**-r _**retries_] [**-i _**interval_] [**-p**] [**-q**] <**-m **| _lockfile_>
       **dotlockfile -l **[**-r _**retries_] [**-i _**interval_] [**-p**] [**-q**] <**-m **| _lockfile_> [**-P**] _cmd_ args ...
       **dotlockfile **-u **| **-t

## DESCRIPTION
       **dotlockfile **is a command line utility to reliably create, test and remove lockfiles.  It cre‐
       ates  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)](https://www.chedong.com/phpMan.php/man/link/2/markdown).  Manpage [_lockfile_create_(3)](https://www.chedong.com/phpMan.php/man/lockfilecreate/3/markdown) describes the used algorithm.

       **dotlockfile **is installed with attribute **SETGID _**mail_ and thus can also be used to lock and un‐
       lock mailboxes _even_ if the mailspool directory is only writable by group mail.

       The  name  **dotlockfile  **comes  from the way mailboxes are locked for updates 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 **dotlockfile _**:)_.

## OPTIONS
### -l     
              cording to option **-r**.  Retry interval can be explicitly set with option **-i**.  This  op‐
              tion (**-l**) is the default, so it can be left off.

              A lockfile is treated as valid,
              •  if it holds the _process-id_ of a running process,
              •  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 sec‐
              onds.  After each retry the sleep interval is increased incrementally by 5 seconds  up
              to  a  maximum sleep of 60 seconds between tries unless overridden by **-i**.  The default
              number of retries is 5.  To try only once, use "**-r 0**".  To try indefinitely,  use  "**-r**
              **-1**".

### -i interval
              Sets a consistent retry interval.

### -u     

### -t     
              filesystems.  For lockfiles on local filesystems the **-p **option is preferable.

### -p     
              ecuted) into the lockfile.  Also when testing for an existing lockfile, check the con‐
              tents 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     
              tem  mailspool  directory  (usually  _/var/mail_) with the username as gotten from _getp‐_
              _wuid_() appended.  If the environment variable _$MAIL_ is  set,  that  is  used  instead.
              Then the string "_.lock_" is appended to get the name of the actual lockfile.

### -q     
              blockfile when it spawns **dotlockfile **as a helper program.

### -P     
              the exit value of the spawned command.

       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 remove 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 library function [_lockfile_create_(3)](https://www.chedong.com/phpMan.php/man/lockfilecreate/3/markdown).  Unlocking a
       non-existent lockfile is not an error.

       Unless the **-P **option was supplied, when a command is executed, the return value does not cor‐
       respond with that of the command that was run.  If locking and unlocking was successful,  the
       exit status is zero.

## NOTES
       The  lockfile  is created exactly as named on the command line.  The extension "_.lock_" is _not_
       automatically appended.

       This utility is a lot like the [_lockfile_(1)](https://www.chedong.com/phpMan.php/man/lockfile/1/markdown) utility included with _procmail_, and the  _mutt_dot‐_
       [_lock_(1)](https://www.chedong.com/phpMan.php/man/lock/1/markdown)  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)](https://www.chedong.com/phpMan.php/man/lockfilecreate/3/markdown) manpage is present in the _liblockfile-dev_ package.

## BUGS
       None known.

## SEE ALSO
       [_lockfile_create_(3)](https://www.chedong.com/phpMan.php/man/lockfilecreate/3/markdown), [_maillock_(3)](https://www.chedong.com/phpMan.php/man/maillock/3/markdown)

## AUTHOR
       Miquel van Smoorenburg

                                          January 10, 2017                            [_DOTLOCKFILE_(1)](https://www.chedong.com/phpMan.php/man/DOTLOCKFILE/1/markdown)