PTHREAD_MUTEX(3) BSD Programmer's Manual PTHREAD_MUTEX(3)NAME
pthread_mutex_init, pthread_mutex_destroy, pthread_mutex_lock,
pthread_mutex_trylock, pthread_mutex_unlock - manipulate pthread mutex
objects
SYNOPSIS
#include <pthread.h>
int
pthread_mutex_init(pthread_mutex_t *mutex,
const pthread_mutexattr_t *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
This interface is defined by IEEE Std1003.1c (``POSIX'').
The pthread_mutex_init() function initializes the mutex pointed to by
mutex with attributes specified by attr. If attr is NULL the default mu-
tex attributes are used. All mutexes should be initialized either stati-
cally using PTHREAD_MUTEX_INITIALIZER or dynamically by calling
pthread_mutex_init(). After successful initialization the mutex is
available for use and unlocked.
The pthread_mutex_destroy() function destroys the mutex pointed to by
mutex, returning it to an uninitialized state. A destroyed mutex may be
re-initialized by calling pthread_mutex_init().
The pthread_mutex_lock() function locks the mutex pointed to by mutex. If
mutex is already locked, the calling thread will block until the mutex
becomes available. Upon success the pthread_mutex_lock() function re-
turns with the mutex locked and the calling thread as its owner.
The pthread_mutex_trylock() function performs a non-blocking mutex lock
operation. It behaves exactly like pthread_mutex_lock() except that if
any thread (including the calling thread) currently owns the mutex, an
immediate error return is performed.
The pthread_mutex_unlock() function releases a previously locked mutex.
It is an error to call pthread_mutex_unlock() with a mutex not owned by
the caller or that is currently unlocked. If there are threads blocked
on the mutex when pthread_mutex_unlock() is successfully called, the mu-
tex becomes available and thread scheduling priority is used to determine
which thread will acquire the mutex.
RETURN VALUES
On success the pthread_mutex functions all return 0. A non-zero result
indicates that an error occurred.
ERRORS
The pthread_mutex functions may fail and return one of the following er-
rors:
[EAGAIN] The system lacked the necessary resources (other than memo-
ry) to fulfill the requested operation.
[EBUSY] In a call to pthread_mutex_init(), an attempt to re-ini-
tialize a previously initialized mutex that had not been
destroyed was detected. In a call to
pthread_mutex_destroy(), an attempt to destroy a mutex that
is currently in use was detected. In a call to
pthread_mutex_trylock(), a mutex could not be acquired be-
cause it was already locked.
[EDEADLK] In a call to pthread_mutex_lock(), an attempt was made to
lock a mutex that the calling thread already owns.
[EINVAL] The value of a function argument is invalid.
[ENOMEM] Insufficient memory exists to fulfill the requested opera-
tion.
[EPERM] The caller does not have sufficient privilege to perform
the requested operation.
SEE ALSOpthreads(3), pthread_cond(3), pthread_create(3)STANDARDS
The pthread_mutex functions conform to IEEE Std1003.1c (``POSIX'').
HISTORY
The pthread_mutex functions first appeared in BSD/OS 3.0.
BUGS
Mutex attributes are not supported. The attr argument to
pthread_mutex_init() must be passed as NULL.
4th Berkeley Distribution June 3, 1996 2
