pthread_mutex_init

Initializes a mutex with attributes specified by the attr argument.

Syntax

pthread_mutex_init( mutex, attr );

Argument Data Type Access

mutex opaque pthread_mutex_t write attr opaque pthread_ read mutexattr_t

C Binding

#include 


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

Arguments

mutex: Mutex created.
attr: Mutex attributes object to be used in initializing the characteristics of the created mutex.

Description

This routine initializes a mutex with the attributes specified by the attr argument. A mutex is a synchronization object that allows multiple threads to serialize their access to shared data.

The mutex is initialized and set to the unlocked state. If attr is set to NULL, the default mutex attributes are used. The pthread_mutexattr_settype_np routine can be used to specify the type of mutex that is created (normal, recursive, or errorcheck).

See Chapter 2 for more information about mutex usage.

A mutex is a resource of the process, not part of any particular thread. A mutex is neither destroyed nor unlocked automatically when any thread exits. Because mutexes are shared, they may be allocated in heap or static memory but not on a stack.

The PTHREAD_MUTEX_INITIALIZER macro can be used to statically initialize a mutex without calling this routine. Statically initialized mutexes need not be destroyed using pthread_mutex_ destroy. Use this macro as follows: pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER

Only normal mutexes can be statically initialized.

Return Values

If an error condition occurs, this routine returns an integer value indicating the type of error, the mutex is not initialized, and the contents of mutex are undefined. Possible return values are as follows:

Return Description

0 Successful completion. [EAGAIN] The system lacks the necessary resources to initialize a mutex. [ENOMEM] Insufficient memory exists to initialize the mutex. [EBUSY] The implementation has detected an attempt to reinitialize the mutex (a previously initialized, but not yet destroyed mutex). [EINVAL] The value specified by mutex is invalid. [EPERM] The caller does not have privileges to perform this operation.

Associated Routines

   pthread_mutexattr_init
   pthread_mutexattr_gettype_np
   pthread_mutexattr_settype_np
   pthread_mutex_lock
   pthread_mutex_trylock
   pthread_mutex_unlock