shlock/shlock.1

   1 .\"     $NetBSD: shlock.1,v 1.2 1997/10/19 23:08:43 lukem Exp $
   2 .\"
   3 .Dd June 29, 1997
   4 .Dt SHLOCK 1
   5 .Os
   6 .Sh NAME
   7 .Nm shlock
   8 .Nd create or verify a lock file for shell scripts
   9 .Sh SYNOPSIS
  10 .Nm
  11 .Fl f
  12 .Ar lockfile
  13 .Op Fl p Ar PID
  14 .Op Fl u
  15 .Op Fl v
  16 .Sh DESCRIPTION
  17 The
  18 .Nm
  19 command can create or verify a lock file on behalf of a shell or
  20 other script program.
  21 When it attempts to create a lock file, if one already exists,
  22 .Nm
  23 verifies that it is or is not valid.
  24 If valid,
  25 .Nm
  26 will exit with a non-zero exit code.
  27 If invalid,
  28 .Nm
  29 will remove the lock file, and
  30 create a new one.
  31 .Pp
  32 .Nm
  33 uses the
  34 .Xr rename 2
  35 system call to make the final target lock file, which is an atomic
  36 operation (i.e. "dot locking", so named for this mechanism's original
  37 use for locking system mailboxes).
  38 It puts the process ID ("PID") from the command line into the
  39 requested lock file.
  40 .Pp
  41 .Nm
  42 verifies that an extant lock file is still valid by
  43 using
  44 .Xr kill 2
  45 with a zero signal to check for the existence of the process that
  46 holds the lock.
  47 .Pp
  48 The
  49 .Fl f
  50 argument with
  51 .Ar lockfile
  52 is always required.
  53 .Pp
  54 The
  55 .Fl p
  56 option with
  57 .Ar PID
  58 is given when the program is to create a lock file; when absent,
  59 .Nm
  60 will simply check for the validity of the lock file.
  61 .Pp
  62 The
  63 .Fl u
  64 option causes
  65 .Nm
  66 to read and write the PID as a binary pid_t, instead of as ASCII,
  67 to be compatible with the locks created by UUCP.
  68 .Pp
  69 The
  70 .Fl v
  71 option causes
  72 .Nm
  73 to be verbose about what it is doing.
  74 .Sh RETURN VALUES
  75 A zero exit code indicates a valid lock file.
  76 .Sh EXAMPLES
  77 .Ss BOURNE SHELL
  78 .Bd -literal
  79 #!/bin/sh
  80 lckfile=/tmp/foo.lock
  81 if shlock -f ${lckfile} -p $$
  82 then
  83 #       do what required the lock
  84         rm ${lckfile}
  85 else
  86         echo Lock ${lckfile} already held by `cat ${lckfile}`
  87 fi
  88 .Ed
  89 .Ss C SHELL
  90 .Bd -literal
  91 #!/bin/csh -f
  92 set lckfile=/tmp/foo.lock
  93 shlock -f ${lckfile} -p $$
  94 if ($status == 0) then
  95 #       do what required the lock
  96         rm ${lckfile}
  97 else
  98         echo Lock ${lckfile} already held by `cat ${lckfile}`
  99 endif
 100 .Ed
 101 .Pp
 102 The examples assume that the filesystem where the lock file is to
 103 be created is writeable by the user, and has space available.
 104 .Sh HISTORY
 105 .Nm
 106 was written for the first Network News Transfer Protocol (NNTP)
 107 software distribution, released in March 1986.
 108 The algorithm was suggested by Peter Honeyman,
 109 from work he did on HoneyDanBer UUCP.
 110 .Sh AUTHOR
 111 Erik E. Fair <fair@clock.org>
 112 .Sh BUGS
 113 Does not work on NFS or other network filesystem on different
 114 systems because the disparate systems have disjoint PID spaces.
 115 .Pp
 116 Cannot handle the case where a lock file was not deleted, the
 117 process that created it has exited, and the system has created a
 118 new process with the same PID as in the dead lock file.
 119 The lock file will appear to be valid even though the process is
 120 unrelated to the one that created the lock in the first place.
 121 Always remove your lock files after you're done.