mutex(3synch)                                          mutex(3synch)


       NAME
             mutex: mutex_init, mutex_lock, mutex_trylock, mutex_unlock,
             mutex_destroy - overview of mutual exclusion lock routines

       SYNOPSIS
             cc [options] -Kthread file
             #include <synch.h>
             int mutex_init(mutex_t *mutex, int type, void *arg);
             int mutex_lock(mutex_t *mutex);
             int mutex_trylock(mutex_t *mutex);
             int mutex_unlock(mutex_t *mutex);
             int mutex_destroy(mutex_t *mutex);

          Parameters
             mutex  pointer to mutex to be initialized, locked, unlocked,
                    or destroyed

             type   USYNC_THREAD or USYNC_PROCESS

             arg    NULL (reserved for future use)

       DESCRIPTION
             Mutual exclusion locks, or mutexes, are used to serialize the
             execution of threads.  They are typically used to ensure that
             only one thread at a time accesses shared data.  Note that
             mutexes protect data only when the convention of acquiring the
             mutex is faithfully followed before any access of the data.

             The Threads Library provides five routines to manipulate
             mutexes; these are outlined below and described in more detail
             on individual manual pages.

          mutex_init
             mutex_init initializes a mutex to be of type type and in the
             unlocked state.

          mutex_lock
             mutex_lock locks the mutex pointed to by mutex.  If mutex is
             already locked, the calling thread is blocked until mutex
             becomes available.  When mutex_lock returns successfully, the
             caller has locked mutex.

          mutex_trylock
             mutex_trylock attempts once to lock the mutex pointed to by
             mutex.



                           Copyright 1994 Novell, Inc.               Page 1

      mutex(3synch)                                          mutex(3synch)


            If mutex is available, mutex_trylock will return successfully
            with mutex locked.  If mutex is already locked, mutex_trylock
            immediately returns EBUSY to the caller without acquiring
            mutex or blocking.

         mutex_unlock
            mutex_unlock unlocks the mutex pointed to by mutex.

            If there are one or more threads waiting for mutex when
            mutex_unlock is called, at least one waiting thread is allowed
            to try again to lock mutex.

         mutex_destroy
            mutex_destroy destroys the mutex pointed to by mutex.  This
            includes invalidating mutex and freeing any associated
            implementation-allocated dynamic resources.

         USYNC_THREAD and USYNC_PROCESS Mutexes
            Mutexes are initialized to be one of two types: USYNC_THREAD
            or USYNC_PROCESS.  USYNC_THREAD mutexes are available only to
            threads within the current process.  USYNC_PROCESS mutexes can
            be used by threads in different processes.

         General Information
            Mutexes must be initialized, either with mutex_init(3synch) or
            statically (see mutex_init), before being passed to any of the
            other mutex routines.

            Locks acquired with mutex_lock or mutex_trylock must be
            released with mutex_unlock.

            From the point of view of the caller, mutex_lock is atomic:
            even if interrupted by a signal or forkall [see fork(2)],
            mutex_lock will not return until it holds the locked mutex.
            As a consequence, if mutex_lock is interrupted, an error
            indication such as EINTR is never returned to the caller.

      USAGE
         Warnings
            Operations on mutexes are not recursive-a thread can deadlock
            if it attempts to relock a mutex that it already has locked.

            If a thread exits while holding a mutex, the mutex will not be
            unlocked, and other threads waiting for the mutex will wait
            forever.  Similarly, if a process exits while holding a
            USYNC_PROCESS mutex, the mutex will not be unlocked, and other


                          Copyright 1994 Novell, Inc.               Page 2

       mutex(3synch)                                          mutex(3synch)


             processes or threads waiting for the mutex will wait forever.

       REFERENCES
             fork(2), mutex_init(3synch), mutex_destroy(3synch),
             mutex_lock(3synch), mutex_trylock(3synch),
             mutex_unlock(3synch), rmutex(3synch), synch(3synch)










































                           Copyright 1994 Novell, Inc.               Page 3