VMS Help DCE_THREADS, Application Routines, pthread_mutexattr_setkind_np  *Conan The Librarian (sorry for the slow response - running on an old VAX)

  NAME

      pthread_mutexattr_setkind_np - Specifies the mutex type attribute

  SYNOPSIS

      #include <pthread.h>

      int pthread_mutexattr_setkind_np( pthread_mutexattr_t *attr,
                                        int                 kind );

  PARAMETERS

      attr                Mutex attributes object modified.

      kind                New value for the mutex type attribute.  The
                          kind parameter specifies the type of mutex
                          that is created. Valid values are MUTEX_FAST_NP
                          (default), MUTEX_RECURSIVE_NP, and
                          MUTEX_NONRECURSIVE_NP.

  DESCRIPTION

  The pthread_mutexattr_setkind_np() routine sets the mutex type attribute
  that is used when a mutex is created.

  A fast mutex is locked and unlocked in the fastest manner possible.  A
  fast mutex can only be locked (obtained) once.  All subsequent calls to
  pthread_mutex_lock() cause the calling thread to block until the mutex
  is freed by the thread that owns it.  If the thread that owns the mutex
  attempts to lock it again, the thread waits for itself to release the
  mutex (causing a deadlock).

  A recursive mutex can be locked more than once by the same thread
  without causing that thread to deadlock. In other words, a single thread
  can make consecutive calls to pthread_mutex_lock() without blocking.
  The thread must then call pthread_mutex_unlock() the same number of
  times as it called pthread_mutex_lock() before another thread can lock
  the mutex.

  A nonrecursive mutex is locked only once by a thread, like a fast mutex.
  If the thread tries to lock the mutex again without first unlocking it,
  the thread receives an error.  Thus, nonrecursive mutexes are more
  informative than fast mutexes because fast mutexes block in such a case,
  leaving it up to you to determine why the thread no longer executes.
  Also, if someone other than the owner tries to unlock a nonrecursive
  mutex, an error is returned.

  Never use a recursive mutex with condition variables because the impli-
  cit unlock performed for a pthread_cond_wait() or
  pthread_cond_timedwait() might not actually release the mutex. In that
  case, no other thread can satisfy the condition of the predicate.
  This routine is not portable.

  RETURN VALUES

  If the function fails, errno may be set to one of the following values:

    Return   Error      Description
    _____________________________________________________________
     0                  Successful completion.

    -1      [EINVAL]    The value specified by attr or kind is invalid.

    -1      [EPERM]     The caller does not have the appropriate
                        privileges.

    -1      [ERANGE]    One or more parameters supplied have an invalid
                        value.

  RELATED INFORMATION

      FUNCTIONS:  pthread_mutexattr_create
                  pthread_mutexattr_getkind_np
                  pthread_mutex_init