pthread_mutex_init(3T)

NAME

pthread_mutex_init(), pthread_mutex_destroy() — initialize or destroy a mutex

SYNOPSIS

#include <pthread.h>

int pthread_mutex_init( 
   pthread_mutex_t *__restrict mutex, 
   const pthread_mutexattr_t *__restrict attr 
); 

pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;

int pthread_mutex_destroy( 
   pthread_mutex_t *mutex 
); 

PARAMETERS

mutex: Pointer to the mutex to be initialized or destroyed.
attr: Pointer to the attributes object that defines the characteristics of the mutex to be initialized. If the pointer is NULL, default attributes are used.

DESCRIPTION

The pthread_mutex_init() function initializes the mutex referenced by mutex with the attributes attr. If the parameter attr is NULL, the default mutex attributes are used. See pthread_mutexattr_init(3T) for a list of default mutex attributes. After successful initialization, the mutex is initialized, unlocked, and ready to be used in mutex operations. A mutex should be initialized only once or the resulting behavior is undefined. The pthread_once() function provides a way to ensure that a mutex is initialized only once.

The macro PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are statically allocated. These mutexes will be initialized with default attributes. The pthread_mutex_init() function does not need to be called for statically initialized mutexes.

If the process-shared attribute in the mutex attributes object referenced by attr is defined as PTHREAD_PROCESS_SHARED, the mutex must be allocated such that the processes sharing the mutex have access to it. This may be done through the memory-mapping functions (see mmap(2)) or the shared memory functions (see shmget(2)).

The pthread_mutex_destroy() function destroys the mutex referenced by mutex. This function may set mutex to an invalid value. The destroyed mutex can be reinitialized using the function pthread_mutex_init(). If the mutex is used after destruction in any mutex call, the resulting behavior is undefined.

A mutex should be destroyed only when it is unlocked. Destroying a mutex that is currently being used results in undefined behavior.

RETURN VALUE

Upon successful completion, pthread_mutex_init() and pthread_mutex_destroy() return zero. Otherwise, an error number is returned to indicate the error (the errno variable is not set).

ERRORS

If any of the following occur, the pthread_mutex_init() function returns the corresponding error number:

EAGAIN: The necessary resources (other than memory) to initialize mutex were not available.
EBUSY: mutex is an already initialized mutex. However, getting EBUSY for reinitializing the mutex cannot be expected all the time since the behavior of reinitializing the mutex is undefined.
EFAULT: mutex points to an illegal address.
EINVAL: The value specified by mutex or attr is invalid.
ENOMEM: There is insufficient memory available in which to initialize mutex.
EPERM: The caller does not have the necessary permission to perform the mutex initialization.

If any of the following occur, the pthread_mutex_destroy() function returns the corresponding error number:

EBUSY: mutex is currently locked or in use by another thread.
EINVAL: mutex is not a valid mutex.

WARNINGS

The space for the mutex must be allocated before calling pthread_mutex_init(). Undefined behavior will result if the process-shared attribute of attr is PTHREAD_PROCESS_SHARED and the space allocated for the mutex is not accessible to cooperating threads.

AUTHOR

pthread_mutex_init() and pthread_mutex_destroy() were derived from the IEEE POSIX P1003.1c standard.

STANDARDS CONFORMANCE

pthread_mutex_init(): POSIX 1003.1c.
pthread_mutex_destroy(): POSIX 1003.1c.