Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
Threads Librarypthread_mutexattr_getrobust_np(3THR)


NAME

 pthread_mutexattr_getrobust_np, pthread_mutexattr_setrobust_np - get or set robustness attribute of mutex attribute object

SYNOPSIS

 
cc -mt [ flag... ] file... -lpthread [ -lrt library... ]
#include <pthread.h> 
int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *attr, int *robustness);
 int pthread_mutexattr_setrobust_np(pthread_mutexattr_t *attr, int robustness);

DESCRIPTION

 

The following applies only if the symbol _POSIX_THREAD_PRIO_INHERIT is defined, and the mutex attributes object attr should be used only to initialize mutexes that will also be initialized with the protocol attribute having the value PTHREAD_PRIO_INHERIT. See pthread_mutexattr_getprotocol(3THR).

The pthread_mutexattr_setrobust_np() and pthread_mutexattr_getrobust_np() functions set and get the robustness attribute of a mutex attribute object pointed to by attr that was previously created by the function pthread_mutexattr_init(3THR).

The robustness attribute defines the behavior when the owner of a mutex dies. The value of robustness may be ether PTHREAD_MUTEX_ROBUST_NP or PTHREAD_MUTEX_STALLED_NP, which are defined by the header <pthread.h>. The default value of the robustness attribute is PTHREAD_MUTEX_STALLED_NP.

When the owner of a mutex with the PTHREAD_MUTEX_STALLED_NP robustness attribute dies, all future calls to pthread_mutex_lock(3THR) for this mutex will be blocked from progress in an unspecified manner.

When the owner of a mutex with the PTHREAD_MUTEX_ROBUST_NP robustness attribute dies, the mutex is unlocked. The next owner of this mutex acquires it with an error value of EOWNERDEAD. Note that the application must always check the return value from pthread_mutex_lock() for a mutex initialized with the PTHREAD_MUTEX_ROBUST_NP robustness attribute. The new owner of this mutex should then attempt to make the state protected by the mutex consistent, since this state could have been left inconsistent when the last owner died. If the new owner is able to make the state consistent, it should call pthread_mutex_consistent_np(3THR) for the mutex and then unlock the mutex. If for any reason the new owner is not able to make the state consistent, it should not call pthread_mutex_consistent_np() for the mutex, but should simply unlock the mutex. In the latter scenario, all waiters will be awakened and all subsequent calls to pthread_mutex_lock() will fail in acquiring the mutex with an error value of ENOTRECOVERABLE. The mutex can then be made consistent by uninitializing the mutex with the pthread_mutex_destroy() function and reinitializing it with the pthread_mutex_init() function. If the thread that acquired the lock with EOWNERDEAD dies, the next owner will acquire the lock with an error value of EOWNERDEAD.

Note that the mutex may be in memory shared between processes or in memory private to a process, i.e. the "owner" referenced above is a thread, either within or outside the requestor's process.

The mutex memory must be zeroed before initialization.

RETURN VALUES

 

Upon successful completion, the pthread_mutexattr_getrobust_np() and pthread_mutexattr_setrobust_np() functions return 0. Otherwise, an error number is returned to indicate the error.

ERRORS

 

The pthread_mutexattr_getrobust_np() and pthread_mutexattr_setrobust_np() functions will fail if:

EINVAL
The value specified by attr or robustness is invalid.
ENOSYS
The option _POSIX_THREAD_PRIO_INHERIT is not defined and the implementation does not support the function.
ENOTSUP
The value specified by robustness is an unsupported value.

ATTRIBUTES

 

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPEATTRIBUTE VALUE
MT-Level MT-Safe

SEE ALSO

 

mutex(3THR), pthread_mutex_lock(3THR), pthread_mutex_consistent_np(3THR), pthread_mutexattr_getprotocol(3THR), attributes(5), standards(5)


SunOS 5.9Go To TopLast Changed 4 Oct 1999

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.