SHLOCK(1) BSD General Commands Manual SHLOCK(1)

NAME
     sshhlloocckk - create or verify a lock file for shell scripts

SYNOPSIS
     sshhlloocckk -ff lockfile [-pp PID] [-uu] [-vv]

DESCRIPTION
     The sshhlloocckk command can create or verify a lock file on behalf of a shell
     or other script program.  When it attempts to create a lock file, if one
     already exists, sshhlloocckk verifies that it is or is not valid.  If valid,
     sshhlloocckk will exit with a non-zero exit code.  If invalid, sshhlloocckk will
     remove the lock file, and create a new one.

     sshhlloocckk uses the rename(2) system call to make the final target lock file,
     which is an atomic operation (i.e. "dot locking", so named for this mech-
     anism's original use for locking system mailboxes).  It puts the process
     ID ("PID") from the command line into the requested lock file.

     sshhlloocckk verifies that an extant lock file is still valid by using kill(2)
     with a zero signal to check for the existence of the process that holds
     the lock.

     The -ff argument with lockfile is always required.

     The -pp option with PID is given when the program is to create a lock
     file; when absent, sshhlloocckk will simply check for the validity of the lock
     file.

     The -uu option causes sshhlloocckk to read and write the PID as a binary pidt,
     instead of as ASCII, to be compatible with the locks created by UUCP.

     The -vv option causes sshhlloocckk to be verbose about what it is doing.

RETURN VALUES
     A zero exit code indicates a valid lock file.

EEXXAAMMPPLLEESS
   BBOOUURRNNEE SSHHEELLLL
     #!/bin/sh
     lckfile=/tmp/foo.lock
     if shlock -f ${lckfile} -p $$
     then
     #       do what required the lock
             rm ${lckfile}
     else
             echo Lock ${lckfile} already held by `cat ${lckfile}`
     fi

   CC SSHHEELLLL
     #!/bin/csh -f
     set lckfile=/tmp/foo.lock
     shlock -f ${lckfile} -p $$
     if ($status == 0) then
     #       do what required the lock
             rm ${lckfile}
     else
             echo Lock ${lckfile} already held by `cat ${lckfile}`
     endif

     The examples assume that the filesystem where the lock file is to be cre-
     ated is writeable by the user, and has space available.

HISTORY     sshhlloocckk was written for the first Network News Transfer Protocol (NNTP)
     software distribution, released in March 1986.  The algorithm was sug-
     gested by Peter Honeyman, from work he did on HoneyDanBer UUCP.

AUTHOR     Erik E. Fair 

BUGS
     Does not work on NFS or other network filesystem on different systems
     because the disparate systems have disjoint PID spaces.

     Cannot handle the case where a lock file was not deleted, the process
     that created it has exited, and the system has created a new process with
     the same PID as in the dead lock file.  The lock file will appear to be
     valid even though the process is unrelated to the one that created the
     lock in the first place.  Always remove your lock files after you're
     done.

BSD                              June 29, 1997                             BSD