1lockfile-progs(1)              Lockfile programs             lockfile-progs(1)
2
3
4

NAME

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

SYNOPSIS

10       mail-lock [--use-pid] [--retry retry-count]
11       mail-unlock
12       mail-touchlock [--oneshot]
13
14       lockfile-create [--use-pid] [--retry retry-count] [--lock-name] filename
15       lockfile-remove [--lock-name] filename
16       lockfile-touch [--oneshot] [--lock-name] filename
17       lockfile-check [--use-pid] [--lock-name] filename
18

DESCRIPTION

20       Lockfile-progs provides a set a programs that can be used to  lock  and
21       unlock mailboxes and files safely (via liblockfile):
22
23           mail-lock - lock the current user's mailbox
24           mail-unlock - unlock the current user's mailbox
25           mail-touchlock - touch the lock on the current user's mailbox
26
27           lockfile-create - lock a given file
28           lockfile-remove - remove the lock on a given file
29           lockfile-touch - touch the lock on a given file
30           lockfile-check - check the lock on a given file
31
32       By  default, the filename argument refers to the name of the file to be
33       locked, and the name of the lockfile will be filename .lock.   However,
34       if  the  --lock-name argument is specified, then filename will be taken
35       as the name of the lockfile itself.
36
37       Each   of   the   mail    locking    commands    attempts    to    lock
38       /var/spool/mail/<user>,  where  <user>  is the name associated with the
39       effective user ID, as determined by via geteuid(2).
40
41       Once a file is locked, the lock must be touched  at  least  once  every
42       five  minutes or the lock will be considered stale, and subsequent lock
43       attempts will succeed.  Also see the --use-pid  option  and  the  lock‐
44       file_create(3) manpage.
45
46       The  lockfile-check  command  tests whether or not a valid lock already
47       exists.
48
49

OPTIONS

51       -q, --quiet
52           Suppress any output.  Success or failure will only be indicated  by
53           the exit status.
54
55       -v, --verbose
56           Enable diagnostic output.
57
58       -l, --lock-name
59           Do  not append .lock to the filename.  This option applies to lock‐
60           file-create, lockfile-remove, lockfile-touch, or lockfile-check.
61
62       -p, --use-pid
63           Write the parent process id (PPID) to the lockfile whenever a lock‐
64           file  is created, and use that pid when checking a lock's validity.
65           See the lockfile_create(3)  manpage  for  more  information.   This
66           option  applies  to lockfile-create and lockfile-check.  NOTE: this
67           option will not work correctly between machines sharing a  filesys‐
68           tem.
69
70       -o, --oneshot
71           Touch  the lock and exit immediately.  This option applies to lock‐
72           file-touch and mail-touchlock.  When not provided,  these  commands
73           will run forever, touching the lock once every minute until killed.
74
75       -r retry-count, --retry retry-count
76           Try  to  lock  filename  retry-count  times before giving up.  Each
77           attempt will be delayed a bit longer than the  last  (in  5  second
78           increments)  until  reaching  a maximum delay of one minute between
79           retries.  If retry-count is unspecified, the  default  is  9  which
80           will  give  up after 180 seconds (3 minutes) if all 9 lock attempts
81           fail.
82
83

EXAMPLES

85       Locking a file during a lengthy process:
86
87         lockfile-create /some/file
88         lockfile-touch /some/file &
89         # Save the PID of the lockfile-touch process
90         BADGER="$!"
91         do-something-important-with /some/file
92         kill "${BADGER}"
93         lockfile-remove /some/file
94
95

EXIT STATUS

97       0
98           For lockfile-check this indicates that a valid lock exists,  other‐
99           wise it just indicates successful program execution.
100
101       Not 0
102           For lockfile-check a non-zero exit status indicates that the speci‐
103           fied lock does not exist or is not valid.  For  other  programs  it
104           indicates that some problem was encountered.
105

SEE ALSO

107       maillock(3)
108       touchlock(3)
109       mailunlock(3)
110       lockfile_create(3)
111       lockfile_remove(3)
112       lockfile_touch(3)
113       lockfile_check(3)
114
115

AUTHOR

117       Written by Rob Browning <rlb@defaultvalue.org>
118
119
120
1210.1.12                            2008-02-10                 lockfile-progs(1)
Impressum