File: lockfile-progs.1

package info (click to toggle)
lockfile-progs 0.1.10
  • links: PTS
  • area: main
  • in suites: etch, etch-m68k, sarge
  • size: 60 kB
  • ctags: 20
  • sloc: ansic: 166; makefile: 91; sh: 5
file content (129 lines) | stat: -rw-r--r-- 3,441 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
'\" t
.\" ** The above line should force tbl to be a preprocessor **
.\" Man page for man
.\"
.\" Copyright (C), 1998-2004, Rob Browning <rlb@defaultvalue.org>
.\"
.\" You may distribute under the terms of the GNU General Public
.\" License as specified in the file COPYING that comes with the
.\" lockfile\-progs distribution.
.\"
.TH lockfile\-progs 1 "23 April 2001" "0.1.10" "Lockfile programs"
.SH NAME
lockfile\-progs \- command\-line programs to safely lock and unlock
files and mailboxes (via liblockfile).
.SH SYNOPSIS
.\" mail\-lock command line
.B mail\-lock
.RB [\|
\-\-retry
.IR retry\-count
\|]
.br
.\" mail\-unlock command line
.B mail\-unlock
.br
.\" mail\-touchlock command line
.B mail\-touchlock
.RB [\|
\-\-oneshot \|]

.\" lockfile\-create command line
.B lockfile\-create
.RB [\|
\-\-retry
.IR retry\-count
\|]
.IR filename
.br
.\" lockfile\-remove command line
.B lockfile\-remove
.IR filename
.br
.\" lockfile\-touch command line
.B lockfile\-touch
.RB [\|
\-\-oneshot \|]
.IR filename
.SH DESCRIPTION
.B lockfile\-progs
provide a method to lock and unlock mailboxes and files safely (via
liblockfile).

.B mail\-lock:
lock the current user's mailbox.
.br
.B mail\-unlock:
unlock the current user's mailbox.
.br
.B mail\-touchlock:
touch the lock on the current user's mailbox.

Each of the mail locking commands is applied to the file
/var/spool/mail/<user>, if possible, where <user> is the name of the
current user (determined from the effective uid via geteuid(2)).

.B lockfile\-create:
lock a given file.
.br
.B lockfile\-remove:
remove the lock on a given file.
.br
.B lockfile\-touch:
touch the lock on a given file.

Once a file is locked, the lock must be touched at least once every
five minutes, or it will be considered stale and a subsequent attempt
to lock the file will succeed.  For both of the locking commands
.B (mail\-touchlock
and
.B lockfile\-touch),
the \-\-oneshot argument causes the program to touch the lock and exit
immediately.  Otherwise the program will loop forever, touching the
lock once every minute until it is killed.

For both of the locking commands
.B (mail\-lock
and
.B lockfile\-create),
the \-\-retry argument specifies (as an integer) the maximum number of
times to retry locking the file before giving up if attempts are
failing.  Each retry will be delayed a little longer than the last (in
5 second increments) until a maximum delay of one minute between
retries is reached.  The default retry count is 9 which, if all 9
attempts to lock the file fail, will give up after 180 seconds (3
minutes).  Note that the description above matches the one for the
underlying lockfile_create(3) call, but in fact, this option might be
better named \-\-tries since \-\-retry 0 will not try to lock at all.

.SH EXAMPLES

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

.SH "EXIT STATUS"
.TP
.B 0
Successful program execution.
.TP
.B NOT\-0
Some problem was encountered.
.SH "SEE ALSO"
.BR maillock (3), 
.BR touchlock (3),
.BR mailunlock (3),
.BR lockfile\-create (1), 
.BR lockfile\-remove (1),
.BR lockfile\-touch (1),
.BR lockfile_create (3), 
.BR lockfile_remove (3),
.BR lockfile_touch (3).
.SH HISTORY
1998 \- Written by Rob Browning <rlb@defaultvalue.org>.