usr.bin/shlock/shlock.1

   1 .\"     $NetBSD: shlock.1,v 1.14 2014/03/18 18:20:45 riastradh Exp $
   2 .\"
   3 .\" Copyright (c) 2006 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Erik E. Fair.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd November 2, 2012
  31 .Dt SHLOCK 1
  32 .Os
  33 .Sh NAME
  34 .Nm shlock
  35 .Nd create or verify a lock file for shell scripts
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl du
  39 .Op Fl p Ar PID
  40 .Fl f
  41 .Ar lockfile
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 command can create or verify a lock file on behalf of a shell or
  46 other script program.
  47 When it attempts to create a lock file, if one already exists,
  48 .Nm
  49 verifies that it is or is not valid.
  50 If valid,
  51 .Nm
  52 will exit with a non-zero exit code.
  53 If invalid,
  54 .Nm
  55 will remove the lock file, and
  56 create a new one.
  57 .Pp
  58 .Nm
  59 uses the
  60 .Xr link 2
  61 system call to make the final target lock file, which is an atomic
  62 operation (i.e. "dot locking", so named for this mechanism's original
  63 use for locking system mailboxes).
  64 It puts the process ID ("PID") from the command line into the
  65 requested lock file.
  66 .Pp
  67 .Nm
  68 verifies that an extant lock file is still valid by
  69 using
  70 .Xr kill 2
  71 with a zero signal to check for the existence of the process that
  72 holds the lock.
  73 .Pp
  74 The
  75 .Fl d
  76 option causes
  77 .Nm
  78 to be verbose about what it is doing.
  79 .Pp
  80 The
  81 .Fl f
  82 argument with
  83 .Ar lockfile
  84 is always required.
  85 .Pp
  86 The
  87 .Fl p
  88 option with
  89 .Ar PID
  90 is given when the program is to create a lock file; when absent,
  91 .Nm
  92 will simply check for the validity of the lock file.
  93 .Pp
  94 The
  95 .Fl u
  96 option causes
  97 .Nm
  98 to read and write the PID as a binary pid_t, instead of as ASCII,
  99 to be compatible with the locks created by UUCP.
 100 .Sh EXIT STATUS
 101 A zero exit code indicates a valid lock file.
 102 .Sh EXAMPLES
 103 .Ss BOURNE SHELL
 104 .Bd -literal
 105 #!/bin/sh
 106 lckfile=/tmp/foo.lock
 107 if shlock -f ${lckfile} -p $$
 108 then
 109 #       do what required the lock
 110         rm ${lckfile}
 111 else
 112         echo Lock ${lckfile} already held by `cat ${lckfile}`
 113 fi
 114 .Ed
 115 .Ss C SHELL
 116 .Bd -literal
 117 #!/bin/csh -f
 118 set lckfile=/tmp/foo.lock
 119 shlock -f ${lckfile} -p $$
 120 if ($status == 0) then
 121 #       do what required the lock
 122         rm ${lckfile}
 123 else
 124         echo Lock ${lckfile} already held by `cat ${lckfile}`
 125 endif
 126 .Ed
 127 .Pp
 128 The examples assume that the file system where the lock file is to
 129 be created is writable by the user, and has space available.
 130 .Sh SEE ALSO
 131 .Xr flock 1
 132 .Sh HISTORY
 133 .Nm
 134 was written for the first Network News Transfer Protocol (NNTP)
 135 software distribution, released in March 1986.
 136 The algorithm was suggested by Peter Honeyman,
 137 from work he did on HoneyDanBer UUCP.
 138 .Sh AUTHORS
 139 .An Erik E. Fair Aq Mt fair@clock.org
 140 .Sh BUGS
 141 Does not work on NFS or other network file system on different
 142 systems because the disparate systems have disjoint PID spaces.
 143 .Pp
 144 Cannot handle the case where a lock file was not deleted, the
 145 process that created it has exited, and the system has created a
 146 new process with the same PID as in the dead lock file.
 147 The lock file will appear to be valid even though the process is
 148 unrelated to the one that created the lock in the first place.
 149 Always remove your lock files after you're done.