This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).

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

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

SYNOPSIS
     shlock -f lockfile [-p PID] [-u] [-v]

DESCRIPTION
     The shlock 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, shlock verifies that it is or is not valid.
     If valid, shlock will exit with a non-zero exit code.  If invalid, shlock will remove the lock file,
     and create a new one.

     shlock 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 mechanism's original use for locking system mailboxes).  It puts
     the process ID ("PID") from the command line into the requested lock file.

     shlock 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 -f argument with lockfile is always required.

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

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

     The -v option causes shlock to be verbose about what it is doing.

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

EXAMPLES
   BOURNE SHELL
     #!/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

   C SHELL
     #!/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 created is writeable by the user,
     and has space available.

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

AUTHOR
     Erik E. Fair <fair@clock.org>

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