pthread_mutex_timedlock()

Attempt to lock mutex

Synopsis:

#include <pthread.h>
#include <time.h>

int pthread_mutex_timedlock( 
                  pthread_mutex_t * mutex,
                  const struct timespec * abs_timeout );

Library:

libc

Description:

The pthread_mutex_timedlock() function is called to lock the mutex object referenced by mutex. If the mutex is already locked, the calling thread blocks until the mutex becomes available as in the pthread_mutex_lock function. If the mutex can't be locked without waiting for another thread to unlock the mutex, the wait is terminated when the specified timeout expires.

The timeout expires when the absolute time specified by abs_timeout passes, as measured by the clock on which timeouts are based (i.e., when the value of that clock equals or exceeds abs_timeout, or if the absolute time specified by abs_timeout has already been passed at the time of the call. If the Timers option is supported, the timeout is based on the CLOCK_REALTIME clock; if the Timers option isn't supported, the timeout is based on the system clock as returned by the time() function. The resolution of the timeout is the resolution of the clock on which it's based. The timespec datatype is defined in the <time.h> header.

If the mutex can be locked immediately, the validity of the abs_timeout parameter isn't checked, and the function won't fail with a timeout.

As a consequence of the priority inheritance rules (for mutexes initialized with the PRIO_INHERIT protocol), if a timed mutex wait is terminated because its timeout expires, the priority of the owner of the mutex is adjusted as necessary to reflect the fact that this thread is no longer amond the threads waiting for the mutex.

Returns:

Zero on success, or an error number to indicate the error.

Errors:

EAGAIN

The mutex couldn't be acquired because the maximum number of recursive locks for the mutex has been exceeded.

EDEADLK

The current thread already owns the mutex.

EINVAL

The mutex was created with the protocol attribute having the value PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than the mutex' current priority ceiling; the process or thread would have blocked, and the abs_timeout parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million; or the value specified by mutex doesn't refer to an initialized mutex object.

ETIMEDOUT

The mutex couldn't be locked before the specified timeout expired.

Classification:

POSIX 1003.1d (draft)

See also:

pthread_mutex_destroy(), pthread_mutex_lock(), pthread_mutex_trylock(), pthread_mutex_unlock()