pthread_mutex(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
PTHREAD_MUTEX(3)        NetBSD Library Functions Manual       PTHREAD_MUTEX(3)


NAME

     pthread_mutex -- mutual exclusion primitives


LIBRARY

     POSIX Threads Library (libpthread, -lpthread)


SYNOPSIS

     #include <pthread.h>

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

     int
     pthread_mutex_destroy(pthread_mutex_t *mutex);

     int
     pthread_mutex_lock(pthread_mutex_t *mutex);

     int
     pthread_mutex_trylock(pthread_mutex_t *mutex);

     int
     pthread_mutex_unlock(pthread_mutex_t *mutex);

     pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;


DESCRIPTION

     The pthread_mutex_init() function creates a new mutex, with attributes
     specified with attr.  If attr is NULL, the default attributes are used.

     The macro PTHREAD_MUTEX_INITIALIZER can be used to initialize a mutex
     when the default attributes are appropriate and the mutex can be stati-
     cally allocated.  The behavior is similar to pthread_mutex_init() with
     attr specified as NULL, except that no error checking is done.

     The pthread_mutex_destroy() function frees the resources allocated for
     mutex.  It is possible to reinitialize a destroyed mutex, but undefined
     behavior may follow if the destroyed object is otherwise referenced.

     The pthread_mutex_lock() function locks mutex.  If the mutex is already
     locked, the calling thread will block until the mutex becomes available.
     The error conditions may vary depending on the type of the mutex; see
     pthread_mutexattr(3) for additional details.

     The pthread_mutex_trylock() function locks mutex.  If the mutex is
     already locked, pthread_mutex_trylock() will not block waiting for the
     mutex, but will return an error condition.

     The pthread_mutex_unlock() function unlocks an acquired mutex.  When
     operating with the default mutex type, undefined behavior follows if a
     thread tries to unlock a mutex that has not been locked by it, or if a
     thread tries to release a mutex that is already unlocked.


RETURN VALUES

     Upon success all described functions return zero.  Otherwise, an error
     number will be returned to indicate the error.


ERRORS

     pthread_mutex_init() may fail if:

     [EAGAIN]           The system lacks the resources to initialize another
                        mutex.

     [EINVAL]           The value specified by attr is invalid.

     [ENOMEM]           The process cannot allocate enough memory to initial-
                        ize another mutex.

     pthread_mutex_destroy() may fail if:

     [EBUSY]            Mutex is locked by another thread.

     [EINVAL]           The value specified by mutex is invalid.

     pthread_mutex_lock() may fail if:

     [EDEADLK]          A deadlock would occur if the thread blocked waiting
                        for mutex.

     [EINVAL]           The value specified by mutex is invalid.

     pthread_mutex_trylock() may fail if:

     [EBUSY]            Mutex is already locked.

     [EINVAL]           The value specified by mutex is invalid.

     pthread_mutex_unlock() may fail if:

     [EINVAL]           The value specified by mutex is invalid.

     [EPERM]            The current thread does not hold a lock on mutex.


SEE ALSO

     pthread(3), pthread_barrier(3), pthread_cond(3), pthread_mutexattr(3),
     pthread_rwlock(3), pthread_spin(3)


STANDARDS

     These functions conform to IEEE Std 1003.1-2001 (``POSIX.1'').

NetBSD 6.0.3                     July 8, 2010                     NetBSD 6.0.3