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. |
100 | .SH "BUGS" |
101 | The |
102 | .B locking |
103 | program messes with alarms. It tries to put them back the way it found |
104 | them, but may get things wrong. |
105 | . |
106 | .SH "AUTHOR" |
107 | Mark Wooding, <mdw@nsict.org> |