mdw@git.distorted.org.uk Git - misc/blob - locking.1

   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 .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
 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"
 122 Mark Wooding, <mdw@distorted.org.uk>