pthread_mutexattr(3T)          DG/UX R4.11MU05         pthread_mutexattr(3T)


NAME
       pthread_mutexattr: pthread_mutexattr_init, pthread_mutexattr_destroy,
       pthread_mutexattr_getpshared, pthread_mutexattr_setpshared - control
       mutex initialization attributes

SYNOPSIS
       #include <pthread.h>

       int pthread_mutexattr_init(pthread_mutexattr_t *attr);

       int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);

       int pthread_mutexattr_getpshared(pthread_mutexattr_t *attr,
                                        int *pshared);

       int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
                                        int pshared);

   where:
       attr     A pointer to a mutex attributes object
       pshared  For pthread_mutexattr_getpshared(), a pointer to a location
                to store the process-shared attribute; for
                pthread_mutexattr_setpshared(), the new value of the
                process-shared attribute.

DESCRIPTION
       Mutex attributes objects are used to control the initialization of
       mutexes in a way similar to which thread attributes objects are used
       to control the creation of threads.

       DG/UX currently only supports the process-shared attribute for
       mutexes.  This attribute can have a value of 0 or 1.  A value of 0
       (default) indicates that mutexes initialized with this mutex
       attributes object are only allowed to be operated upon by threads
       within the the current process.  A value of 1 indicates that mutexes
       initialized with this mutex attributes object are allowed to be
       operated upon by threads in all processes that have access to the
       memory in which the mutex is allocated.  Whenever possible, the
       default value of 0 for the process-shared attribute should be used,
       as intraprocess mutexes are more efficient than interprocess mutexes.

       The pthread_mutexattr_init() function initializes a mutex attributes
       object with the default value for the process-shared attribute.  In a
       call to pthread_mutex_init(), passing a pointer to such a newly
       initialized mutex attributes object is equivalent to passing a NULL
       pointer.

       The pthread_mutexattr_destroy() function destroys the mutex
       attributes object pointed to by attr.

       The pthread_mutexattr_setpshared() function is used to set the
       process-shared attribute in an initialized attributes object pointed
       to by attr.  The pthread_mutexattr_getpshared() function returns the
       value of the process-shared attribute from the attributes object
       pointed to by attr.

       After a mutex attributes object has been used in a call to
       pthread_mutex_init(), it is no longer associated with the initialized
       mutex.  The mutex attributes object can be freely destroyed,
       modified, or used again to initialize another mutex.

DIAGNOSTICS
   Returns
       If successful, pthread_mutexattr_init(),
       pthread_mutexattr_setpshared(), and pthread_mutexattr_destroy()
       return 0.  Otherwise each returns -1 and sets errno to indicate the
       error.

       If successful, pthread_mutexattr_getpshared() returns 0 and stores
       the value of the process-shared attribute from the mutex attributes
       object pointed to by attr into the location pointed to by pshared;
       otherwise it returns -1 and sets errno to indicate the error.

   Errors
       For each of the following conditions, pthread_mutexattr_destroy(),
       pthread_mutexattr_getpshared(), and pthread_mutexattr_setpshared()
       return -1 and set errno to the corresponding value:

       [EINVAL]  An invalid mutex attributes object has been specified.
                 This occurs when DG/UX has detected that the mutex
                 attributes object pointed to by attr has not been
                 initialized by a previous call to pthread_mutexattr_init()
                 or has been corrupted.

       For each of the following conditions, pthread_mutexattr_setpshared()
       returns -1 and sets errno to the corresponding value:

       [EINVAL]  The value given by pshared is not 0 or 1.

SEE ALSO
       pthread_mutex_init(3T), pthread_mutex_lock(3T),
       pthread_mutex_unlock(3T), pthread_condattr_init(3T),
       pthread_cond_init(3T).

NOTES
       The DG/UX system defines the symbol {_POSIX_THREADS_PROCESS_SHARED},
       indicating that it supports the process-shared attribute for mutexes
       and condition variables.

       The DG/UX system does not currently define the symbols
       {_POSIX_THREADS_PRIO_INHERIT} and {_POSIX_THREADS_PRIO_PROTECT},
       indicating that it does not support the priority inheritance or
       priority ceiling protocol for mutexes.  As a result, the following
       related functions are neither supported nor documented:
       pthread_mutexattr_setprotocol(), pthread_mutexattr_getprotocol(),
       pthread_mutexattr_setprio_ceiling(),
       pthread_mutexattr_getprio_ceiling().

       An application need not be multi-threaded to use process-shared
       mutexes.  However, it must compile and link against the thread
       interfaces.  Process-shared mutexes are significantly faster than
       traditional Unix semaphores, particularly in the uncontended cases.


Licensed material--property of copyright holder(s)