abilock(3X)

NAME
     init_lock, acquire_lock, release_lock, stat_lock, spin_lock - ABI mutual
     exclusion primitives

SYNOPSIS
     #include <abi_mutex.h>

     int init_lock(abilock_t *lck);

     int acquire_lock(abilock_t *lck);

     int release_lock(abilock_t *lck);

     int stat_lock(abilock_t *lck);

     void spin_lock(abilock_t *lck);

DESCRIPTION
     These routines provide a simple, standard interface to base level mutual
     exclusion primitives.  They are found in the library ``libmutex.so'', and
     is loaded if the option ``-lmutex'' is used with cc(1) or ld(1).

     The parameter lck must point to memory shared by all processes wishing to
     acquire or test the lock.

     The contents of the structure abilock_t are as follows:
          typedef struct {
               unsigned int abi_lock;
          } abilock_t;

     The function init_lock must be called on a lock before any of the other
     functions.  It initializes the lock to an unlocked state.  A non-zero
     return status will indicate an error.

     acquire_lock tries once to acquire the lock referenced by lck.  It
     returns zero if the lock was acquired, otherwise non-zero.  acquire_lock
     can always fail, even if it is known that the lock is free and there is
     only one process, this implies that acquire_lock should always be called
     in a loop.

     spin_lock will always acquire the lock. If the lock is not immediately
     available, the calling process will either spin (busy-wait) or be
     suspended until the lock becomes available.  There is no implied policy
     as to which (if there is more than one) waiting process will be granted
     the lock.

     stat_lock returns the current state of the lock referenced by lck without
     attempting to acquire the lock.  It returns UNLOCKED if the lock is free,
     otherwise LOCKED.
     release_lock unconditionally releases the lock pointed to by lck.  The
     ability for one process to release the lock of another process is
     permitted.  A non-zero return status will indicate an error.

     These routines will work for locks shared between 32-bit and 64-bit user
     programs.

SEE ALSO
     nanosleep(2), sginap(2), usinit(3P).

DIAGNOSTICS
     init_lock, acquire_lock, and release_lock return 0 if the operation was a
     success, otherwise a non-zero value.  spin_lock returns no value.

WARNINGS
     No locks are ever freed automatically by the system.  Locks acquired by a
     process that terminates remain locked.

     Since looping is necessary when attempting to acquire a lock using
     acquire_lock, the user process could find itself in a long busy-wait
     loop.  To avoid wasting CPU cycles, programs should implement some kind
     of back-off strategy, perhaps calling sginap(2) or nanosleep(2) after
     some number of unsuccessful calls to acquire_lock.

     Even though stat_lock returns status indicating that the lock is
     available, a call to acquire_lock could still fail.