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 Library Functionspthread_mutex_init(3THR)


NAME

 pthread_mutex_init, pthread_mutex_destroy - initialize or destroy a mutex

SYNOPSIS

 
cc -mt [ flag... ] file... -lpthread [ -lrt library... ]
#include <pthread.h> 
int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr);
 int pthread_mutex_destroy(pthread_mutex_t *mutex,
pthread_mutex_t mutex= PTHREAD_MUTEX_INITIALIZER

DESCRIPTION

 

The pthread_mutex_init() function initializes the mutex referenced by mutex with attributes specified by attr. If attr is NULL, the default mutex attributes are used; the effect is the same as passing the address of a default mutex attributes object. Upon successful initialization, the state of the mutex becomes initialized and unlocked.

Attempting to initialize an already initialized mutex results in undefined behavior.

The pthread_mutex_destroy() function destroys the mutex object referenced by mutex; the mutex object becomes, in effect, uninitialized. A destroyed mutex object can be re-initialized using pthread_mutex_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

It is safe to destroy an initialized mutex that is unlocked. Attempting to destroy a locked mutex results in undefined behavior.

In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are statically allocated. The effect is equivalent to dynamic initialization by a call to pthread_mutex_init() with parameter attr specified as NULL, except that no error checks are performed.

RETURN VALUES

 

If successful, the pthread_mutex_init() and pthread_mutex_destroy() functions return 0. Otherwise, an error number is returned to indicate the error.

ERRORS

 

The pthread_mutex_init() function will fail if:

EAGAIN
The system lacked the necessary resources (other than memory) to initialize another mutex.
EBUSY
An attempt was detected to re-initialize the object referenced by mutex, a robust mutex previously initialized but not yet destroyed.
EINVAL
The value specified by attr has not been initialized using pthread_mutexattr_init(3THR).
EINVAL
An attempt was made to initialize mutex to be robust and not PTHREAD_PRIO_INHERIT.
EINVAL
An attempt was made to initalize mutex to be PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT and the type of the mutex to be PTHREAD_MUTEX_ERRORCHECK or PTHREAD_MUTEX_RECURSIVE.
EINVAL
An attpemt was made to initalize mutex to be PTHREAD_PROCESS_SHARED and the type of the mutex to be PTHREAD_MUTEX_RECURSIVE.
EINVAL
The process-shared attribute associated with attr is invalid.
ENOMEM
Insufficient memory exists to initialize the mutex.
EPERM
The caller does not have the privilege to perform the operation.

The pthread_mutex_init() function may fail if:

EBUSY
An attempt was detected to re-initialize the object referenced by mutex, a mutex previously initialized but not yet destroyed. This condition is not reported.
EINVAL
The value specified by attr or mutex is invalid. This condition is not reported.

The pthread_mutex_destroy() function may fail if:

EBUSY
An attempt was detected to destroy the object referenced by mutex while it is locked or referenced (for example, while being used in a pthread_cond_wait(3THR) or pthread_cond_timedwait(3THR)) by another thread. This condition is not reported.
EINVAL
The value specified by mutex is invalid. This condition is not reported.

ATTRIBUTES

 

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

ATTRIBUTE TYPEATTRIBUTE VALUE
MT-LevelMT-Safe

SEE ALSO

 

mutex(3THR), pthread_cond_timedwait(3THR), pthread_cond_wait(3THR), pthread_mutex_getprioceiling(3THR), pthread_mutex_lock(3THR), pthread_mutex_unlock(3THR), pthread_mutex_setprioceiling(3THR), pthread_mutex_trylock(3THR), pthread_mutexattr_init(3THR), pthread_mutexattr_getpshared(3THR), pthread_mutexattr_setpshared(3THR) attributes(5), standards(5)


SunOS 5.9Go To TopLast Changed 14 Mar 2000

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