| | 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@distorted.org.uk> |
~mdw / misc / blame_incremental