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
 102 .Pp
 103 The examples assume that the filesystem where the lock file is to
 104 be created is writeable by the user, and has space available.
 105 .Sh HISTORY
 106 .Nm
 107 was written for the first Network News Transfer Protocol (NNTP)
 108 software distribution, released in March 1986.
 109 The algorithm was suggested by Peter Honeyman,
 110 from work he did on HoneyDanBer UUCP.
 111 .Sh AUTHOR
 112 Erik E. Fair <fair@clock.org>
 113 .Sh BUGS
 114 Does not work on NFS or other network filesystem on different
 115 systems because the disparate systems have disjoint PID spaces.
 116 .Pp
 117 Cannot handle the case where a lock file was not deleted, the
 118 process that created it has exited, and the system has created a
 119 new process with the same PID as in the dead lock file.
 120 The lock file will appear to be valid even though the process is
 121 unrelated to the one that created the lock in the first place.
 122 Always remove your lock files after you're done.