1PTHREAD_MUTEX_TIMEDLOCK(P) POSIX Programmer's ManualPTHREAD_MUTEX_TIMEDLOCK(P)
2
3
4

NAME

6       pthread_mutex_timedlock - lock a mutex (ADVANCED REALTIME)
7

SYNOPSIS

9       #include <pthread.h>
10       #include <time.h>
11
12       int pthread_mutex_timedlock(pthread_mutex_t *restrict mutex,
13              const struct timespec *restrict abs_timeout);
14
15

DESCRIPTION

17       The pthread_mutex_timedlock() function shall lock the mutex object ref‐
18       erenced by mutex. If the mutex is already locked,  the  calling  thread
19       shall   block   until   the   mutex   becomes   available   as  in  the
20       pthread_mutex_lock() function. If the mutex cannot  be  locked  without
21       waiting for another thread to unlock the mutex, this wait shall be ter‐
22       minated when the specified timeout expires.
23
24       The timeout shall expire when the absolute time specified by  abs_time‐
25       out  passes, as measured by the clock on which timeouts are based (that
26       is, when the value of that clock equals or exceeds abs_timeout), or  if
27       the  absolute  time specified by abs_timeout has already been passed at
28       the time of the call.
29
30       If the Timers option is supported, the timeout shall be  based  on  the
31       CLOCK_REALTIME  clock; if the Timers option is not supported, the time‐
32       out shall be based on the system clock as returned by the time()  func‐
33       tion.
34
35       The  resolution  of the timeout shall be the resolution of the clock on
36       which it is based. The timespec data type is defined  in  the  <time.h>
37       header.
38
39       Under  no  circumstance  shall  the function fail with a timeout if the
40       mutex can be locked immediately. The validity of the abs_timeout param‐
41       eter need not be checked if the mutex can be locked immediately.
42
43       As  a  consequence  of the priority inheritance rules (for mutexes ini‐
44       tialized with the PRIO_INHERIT protocol), if a timed mutex wait is ter‐
45       minated  because  its timeout expires, the priority of the owner of the
46       mutex shall be adjusted as necessary to  reflect  the  fact  that  this
47       thread is no longer among the threads waiting for the mutex.
48

RETURN VALUE

50       If  successful,  the  pthread_mutex_timedlock()  function  shall return
51       zero; otherwise, an error number shall  be  returned  to  indicate  the
52       error.
53

ERRORS

55       The pthread_mutex_timedlock() function shall fail if:
56
57       EINVAL The  mutex  was  created  with the protocol attribute having the
58              value PTHREAD_PRIO_PROTECT and the calling thread's priority  is
59              higher than the mutex' current priority ceiling.
60
61       EINVAL The  process  or  thread would have blocked, and the abs_timeout
62              parameter specified a nanoseconds field value less than zero  or
63              greater than or equal to 1000 million.
64
65       ETIMEDOUT
66              The  mutex  could  not  be  locked  before the specified timeout
67              expired.
68
69
70       The pthread_mutex_timedlock() function may fail if:
71
72       EINVAL The value specified by mutex does not refer  to  an  initialized
73              mutex object.
74
75       EAGAIN The  mutex  could  not be acquired because the maximum number of
76              recursive locks for mutex has been exceeded.
77
78       EDEADLK
79              The current thread already owns the mutex.
80
81
82       This function shall not return an error code of [EINTR].
83
84       The following sections are informative.
85

EXAMPLES

87       None.
88

APPLICATION USAGE

90       The pthread_mutex_timedlock() function is part of the Threads and Time‐
91       outs options and need not be provided on all implementations.
92

RATIONALE

94       None.
95

FUTURE DIRECTIONS

97       None.
98

SEE ALSO

100       pthread_mutex_destroy()  ,  pthread_mutex_lock()  ,  pthread_mutex_try‐
101       lock() , time() , the Base Definitions volume of  IEEE Std 1003.1-2001,
102       <pthread.h>, <time.h>
103

105       Portions  of  this text are reprinted and reproduced in electronic form
106       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
107       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
108       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
109       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
110       event of any discrepancy between this version and the original IEEE and
111       The  Open Group Standard, the original IEEE and The Open Group Standard
112       is the referee document. The original Standard can be  obtained  online
113       at http://www.opengroup.org/unix/online.html .
114
115
116
117IEEE/The Open Group                  2003           PTHREAD_MUTEX_TIMEDLOCK(P)
Impressum