pthread_mutex_init(3pthread)

pthread_mutex_init, pthread_mutex_destroy -- initialize, destroy a mutex

Synopsis

   cc [options] -Kthread file
   
   #include <pthread.h>
   

   int pthread_mutex_init(pthread_mutex_t *mutex,
   	const pthread_mutexattr_t *attr);
   int pthread_mutex_destroy(pthread_mutex_t *mutex);
   	const pthread_mutexattr_t attr);
   pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;

Description

pthread_mutex_init initializes the mutual exclusion lock (mutex) to the unlocked state and with attributes specified by attr. Once initialized, the mutex can be used any number of times without being reinitialized.

pthread_mutex_destroy destroys the mutex pointed to by mutex. This includes invalidating the mutex and freeing any associated implementation-allocated dynamic resources. Any user-allocated dynamic storage is unaffected by pthread_mutex_destroy and must be explicitly released by the program.

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.

mutex is a pointer to the mutex to be initialized or destroyed. 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.

Static mutex initialization

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 attr specified as NULL, except that no error checks are performed.

Return values

pthread_mutex_init and pthread_mutex_destroy return zero for success and an error number for failure.

Diagnostics

pthread_mutex_init returns the following values if the corresponding conditions are detected:

EINVAL: Invalid attr argument specified.

pthread_mutex_destroy returns the following values if the corresponding conditions are detected:

EBUSY: mutex locked or another thread waiting to acquire mutex. An attempt has been detected to destroy the object referenced by mutex while it is locked or referenced (for example, while being used in a pthread_cond_wait or pthread_cond_timedwait) by another thread.
EINVAL: Invalid argument specified.

Warnings

Attempting to initialize an already initialized mutex results in undefined behavior. pthread_mutex_init does not examine the mutex argument before initializing it. If pthread_mutex_init is called more than once for the same mutex, it will overwrite its state. It is the user's responsibility to ensure that pthread_mutex_init is only called once for each mutex.

Standards Compliance

The Single UNIX Specification, Version 2; The Open Group.

References

Intro(3pthread), pthread_mutex_lock(3pthread), pthread_mutex_trylock(3pthread), pthread_mutex_unlock(3pthread), pthread_mutexattr_getprotocol(3pthread), pthread_mutexattr_getpshared(3pthread), pthread_mutexattr_setprotocol(3pthread), pthread_mutexattr_setpshared(3pthread), pthread(4)