1DOTLOCKFILE(1)                 Cistron Utilities                DOTLOCKFILE(1)
2
3
4

NAME

6       dotlockfile - Utility to manage lockfiles
7

SYNOPSIS

9       dotlockfile -l [-r retries] [-p] <-m | lockfile>
10       dotlockfile -l [-r retries] [-p] <-m | lockfile> cmd args...
11       dotlockfile -u | -t
12

DESCRIPTION

14       dotlockfile  is  a  command  line  utility to reliably create, test and
15       remove lockfiles.  It creates  lockfiles  reliably  on  local  and  NFS
16       filesystems,  because  the  crucial  steps of testing for a preexisting
17       lockfile and creating it are performed atomically by a single  call  to
18       link(2).  Manpage lockfile_create(3) describes the used algorithm.
19
20       dotlockfile  is  installed with attribute SETGID mail and thus can also
21       be used to lock and unlock mailboxes even if the mailspool directory is
22       only writable by group mail.
23
24       The  name  dotlockfile  comes  from  the  way  mailboxes are locked for
25       updates on a lot of UNIX systems.  A lockfile is created with the  same
26       filename as the mailbox but with the string ".lock" appended.
27
28       The names dotlock and lockfile were already taken - hence the name dot‐
29       lockfile :).
30

OPTIONS

32       -l     Create a lockfile if no preexisting  valid  lockfile  is  found,
33              else  wait and retry according to option -r.  This option is the
34              default, so it can be left off.
35
36              A lockfile is treated as valid,
37              ·  if it holds the process-id of a running process,
38              ·  or if it does not hold any process-id and  has  been  touched
39              less than 5 minutes ago (timestamp is younger than 5 minutes).
40
41       -r retries
42              The  number  of times dotlockfile retries to acquire the lock if
43              it failed the first time before giving up.   The  initial  sleep
44              after  failing  to  acquire  the  lock is 5 seconds.  After each
45              retry the sleep intervall is increased incrementally  by  5 sec‐
46              onds  up  to  a  maximum sleep of 60 seconds between tries.  The
47              default number of retries is 5.  To try only once, use  "-r  0".
48              To try indefinitely, use "-r -1".
49
50       -u     Remove a lockfile.
51
52       -t     Touch  an  existing lockfile (update the timestamp).  Useful for
53              lockfiles on NFS filesystems.  For lockfiles on  local  filesys‐
54              tems the -p option is preferable.
55
56       -p     Write  the  process-id  of  the  calling process (or dotlockfile
57              itself if a command is executed) into the lockfile.   Also  when
58              testing  for  an  existing  lockfile, check the contents for the
59              process-id of a running process to verify  if  the  lockfile  is
60              still  valid.   Obviously  useful  only  for  lockfiles on local
61              filesystems.
62
63       -m     Lock or unlock the current users mailbox.  The path to the mail‐
64              box   is   the   default  system  mailspool  directory  (usually
65              /var/mail) with the username as gotten from getpwuid() appended.
66              If  the environment variable $MAIL is set, that is used instead.
67              Then the string ".lock" is appended  to  get  the  name  of  the
68              actual lockfile.
69
70       lockfile
71              The lockfile to be created or removed.  Must not be specified if
72              the -m option is given.
73
74       command
75              Create lockfile, run the command , wait  for  it  to  exit,  and
76              remove lockfile.
77

RETURN VALUE

79       Zero  on  success, and non-zero on failure.  When locking (the default,
80       or with the -l option) dotlockfile  returns  the  same  values  as  the
81       library function lockfile_create(3).  Unlocking a non-existant lockfile
82       is not an error.
83
84       If a command is executed, the return value  does  not  correspond  with
85       that of the command that was run. If the locking and unlocking was suc‐
86       cesful, the exit status is always zero.
87

NOTES

89       The lockfile is created exactly as named  on  the  command  line.   The
90       extension ".lock" is not automatically appended.
91
92       This  utility is a lot like the lockfile(1) utility included with proc‐
93       mail, and the mutt_dotlock(1) utility included with mutt.  However  the
94       command-line  arguments  differ,  and so does the return status.  It is
95       believed, that dotlockfile is the most flexible  implementation,  since
96       it  automatically  detects  when  it  needs to use priviliges to lock a
97       mailbox, and does it safely.
98
99       The above  mentioned  lockfile_create(3)  manpage  is  present  in  the
100       liblockfile-dev package.
101

BUGS

103       None known.
104

SEE ALSO

106       lockfile_create(3), maillock(3)
107

AUTHOR

109       Miquel van Smoorenburg, miquels@cistron.nl
110
111
112
113                               Januari 10, 2017                 DOTLOCKFILE(1)
Impressum