NAME

       locks — libbash library that implements locking (directory based).

       This library is not throughoutly tested - use with caution!

SYNOPSIS

       dirInitLock      ⟨object⟩ [⟨spin⟩]
       dirTryLock       ⟨object⟩
       dirLock          ⟨object⟩
       dirUnlock        ⟨object⟩
       dirDestroyLock   ⟨object⟩

DESCRIPTION

   General
       locks  is  a collection of functions that implement locking (mutex like) in bash scripting language.  The
       whole idea is based on the fact that directory creation/removal is an atomic process.   The  creation  of
       this library was inspired by studying CVS locks management.

       Same  lock  object  can by used by several processes to serialize access to some shared resource.  (Well,
       yeah, this what locks were invented for...) To actually do this,  processes  just  need  to  access  lock
       object by the same name.

   Functions list:
            dirInitLock      Initialize a lock object for your proccess

            dirTryLock       Try to lock the lock object - give up if its already locked

            dirLock          Lock the lock object - will block until object is unlocked

            dirUnlock        Unlock the lock object

            dirDestroyLock   Destroy the lock object - free resources

       Detailed interface description follows.

FUNCTIONS DESCRIPTIONS

   dirInitLock ⟨object⟩ [⟨spin⟩]
       Initialize  a lock object for your process.  Only after a lock is initialized, your proccess will be able
       to use it.  Notice: This action does not lock the object.

       The lock can be set on two types of objects. The first is an existing directory.  In this  case,  Aq  dir
       must be a path (relative or full). The path must contain a ‘/’.  The second is an abstract object used as
       a  lock.  In  this case, the name of the lock will not contain any ‘/’.  This can be used to create locks
       without creating real directories for them.  Notice: Do not call your lock object ‘.lock’.

       Parameters:

         ⟨object⟩
           The name of the lock object (either existing directory or abstract name)

         ⟨spin⟩
           The time (in seconds) that the funtion dirLock will  wait  between  two  runs  of  dirTryLock.   This
           parameter  is  optional,  and its value generally should be less then 1.  If ommited, a default value
           (0.01) is set.

       Return Value:

         One of the following:
         0    The action finished successfully.
         1    The action failed. You do not have permissions to preform it.
         3    The directory path could not be resolved. Possibly parameter  does  contain  ‘/’,  but  refers  to
              directory that does not exist.

   dirTryLock ⟨object⟩
       Try to lock the lock object. The function always returns immediately.

       Parameters:

         ⟨object⟩
           The object that the lock is set on.

       Return Value:

         One of the following:
         0    The action finished successfully.
         1    The action failed. The object is already locked.
         2    The action failed. Your proccess did not initialize a lock for the object.
         3    The directory path could not be resolved.

   dirLock ⟨object⟩
       Lock  given  lock object.  If the object is already locked - the function will block untill the object is
       unlocked.  After each try (dirTryLock) the function will sleep for spin seconds (spin  is  defined  using
       dirInitLock ).

       Parameters:

         ⟨object⟩
           The directory that the lock is set on.

       Return Value:

         One of the following:
         0    The action finished successfully.
         2    The action failed. Your proccess did not initialize a lock for the directory.
         3    The directory path could not be resolved.

   dirUnlock ⟨dir⟩
       Unlock the lock object.

       Parameters:

         ⟨object⟩
           The object that the lock is set on.

       Return Value:

         One of the following:
         0    The action finished successfully.
         2    The action failed. Your proccess did not initialize the lock.
         3    The directory path could not be resolved.

   dirDestroyLock ⟨object⟩
       Destroys  the lock object.  After this action the proccess will no longer be able to use the lock object.
       To use  the object after this action is done, one must initialize the lock, using dirInitLock.

       Parameters:

         ⟨object⟩
           The directory that the lock is set on.

       Return Value:

         One of the following:
         0    The action finished successfully.
         1    The action failed. The directory is locked by your own proccess. Unlock it first.
         2    The action failed. Your proccess did not initialize the lock.
         3    The directory path could not be resolved.

EXAMPLES

       Creating an abstract lock named mylock, with 0.1 second spintime:
             $ dirInitLock mylock 0.1 # $?=0
       Locking it:
             $ dirLock mylock # $?=0
       Trying once to lock it again:
             $ dirTryLock mylock # $?=1
       Trying to lock it again:
             $ dirLock mylock # Will wait forever
       Unlocking:
             $ dirUnlock mylock # $?=0
       Destroying the lock:
             $ dirDestroyLock mylock # $?=0
       Trying to lock again:
             $ dirLock mylock # $?=2
       Creating a lock on the directory ./mydir, with default spin time:
             $ dirInitLock ./mydir # $?=0

AUTHORS

       Hai Zaar <haizaar@haizaar.com>
       Gil Ran <gil@ran4.net>

SEE ALSO

       ldbash(1), libbash(1)

Linux                                                UNDATED                                            LOCKS(3)