Commit | Line | Data |
---|---|---|
f342fce2 | 1 | .TH "locking" 1 "11 May 2003" "Mark Wooding" "Toys" |
2 | .SH NAME | |
3 | locking \- run a program with a lock held | |
4 | . | |
5 | .SH SYNOPSIS | |
6 | .B locking | |
7 | .RB [ \-cfwx ] | |
8 | .RB [ \-p | |
9 | .IR realprog ] | |
10 | .RB [ \-t | |
11 | .IR time ] | |
12 | .I file | |
13 | .I prog | |
14 | .IR args ... | |
15 | . | |
16 | .SH "DESCRIPTION" | |
17 | The | |
18 | .B locking | |
19 | program opens and locks | |
20 | .I file | |
21 | while it runs some program | |
22 | .IR prog . | |
23 | This is handy in shell scripts and (particularly) crontab entries. It | |
24 | was initially written to ensure that news fetches only occurred if the | |
25 | previous one had completed. | |
26 | .PP | |
27 | The program uses | |
28 | .BR fcntl (2)-style | |
29 | locking. It will not leave stale locks lying around: the lock is | |
30 | released if | |
31 | .I prog | |
32 | or the | |
33 | .B locking | |
34 | program itself quits for any reason. | |
35 | .PP | |
36 | The following options are supported: | |
37 | .TP | |
38 | .B "\-h, \-\-help" | |
39 | Write a full help message to stdout, and exit zero. | |
40 | .TP | |
41 | .B "\-v, \-\-version" | |
42 | Write the version number to stdout, and exit zero. | |
43 | .TP | |
44 | .B "\-u, \-\-usage" | |
45 | Write a brief usage message to stdout, and exit zero. | |
46 | .TP | |
47 | .BR "\-c, \-\-" [ "no\-" ] "create" | |
48 | Create | |
49 | .I file | |
50 | if it doesn't already exist. The file is created with mode 666 as | |
51 | modified by the process's umask in the usual way. This is the default | |
52 | behaviour. The options | |
53 | .B +c | |
54 | or | |
55 | .B \-\-no\-create | |
56 | will cause | |
57 | .B locking | |
58 | to fail if the file does not already exist. | |
59 | .TP | |
60 | .BR "\-f, \-\-" [ "no\-" ] "fail" | |
61 | Fail (report an error and exit nonzero) if | |
62 | .I file | |
63 | is already locked. The default behaviour is to exit successfully | |
64 | without running | |
65 | .IR prog . | |
66 | .TP | |
67 | .BR "\-w, \-\-" [ "no\-" ] "wait" | |
68 | Wait for the lock on | |
69 | .I file | |
70 | to become available. The default behaviour is to give up immediately. | |
71 | .TP | |
72 | .BR "\-x, \-\-" [ "no\-" ] "exclusive" | |
73 | Obtain an exclusive lock on the file. This is the default. The options | |
74 | .B +x | |
75 | or | |
76 | .B \-\-no\-exclusive | |
77 | obtain a non-exclusive lock on the file instead. | |
78 | .TP | |
79 | .BI "\-p, \-\-program=" realprog | |
80 | Run the program | |
81 | .IR realprog , | |
82 | passing it | |
83 | .I prog | |
84 | as its first argument. The default behaviour is to run | |
85 | .IR prog . | |
86 | .TP | |
87 | .BI "\-t, \-\-timeout=" time | |
88 | Wait for | |
89 | .I time | |
90 | (an integer, optionally followed by | |
91 | .RB ` d ', | |
92 | .RB ` h ', | |
93 | .RB ` m ', | |
94 | or | |
95 | .RB ` s ' | |
96 | for days, hours, minutes or seconds, respectively) for the lock to | |
97 | become available, and then give up. This only makes sense with the | |
98 | .B \-\-wait | |
99 | option, so that is turned on automatically. | |
ed1b4ef8 MW |
100 | .PP |
101 | It is safe to unlink or atomically replace the lockfile while holding | |
102 | the lock, though these actions will release the lock immediately. To | |
103 | safely delete the lockfile, for example, run | |
104 | .IP | |
105 | .B "locking lock rm lock" | |
106 | .PP | |
107 | Similarly, a file can be updated safely by | |
108 | .IP | |
109 | .nf | |
110 | .ft B | |
111 | locking file sh -c \e | |
112 | \h'8m'"update-file file >file.new && mv file.new file" | |
113 | .fi | |
114 | .ft R | |
f342fce2 | 115 | .SH "BUGS" |
116 | The | |
117 | .B locking | |
118 | program messes with alarms. It tries to put them back the way it found | |
119 | them, but may get things wrong. | |
120 | . | |
121 | .SH "AUTHOR" | |
71d8432e | 122 | Mark Wooding, <mdw@distorted.org.uk> |