1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
<table class="head">
<tr>
<td class="head-ltitle">PTHREAD_RWLOCK_RDLOCK(3)</td>
<td class="head-vol">Library Functions Manual</td>
<td class="head-rtitle">PTHREAD_RWLOCK_RDLOCK(3)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">pthread_rwlock_rdlock</code>,
<code class="Nm">pthread_rwlock_tryrdlock</code> —
<span class="Nd">acquire a read/write lock for reading</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="LIBRARY"><a class="permalink" href="#LIBRARY">LIBRARY</a></h1>
<p class="Pp"><span class="Lb">POSIX Threads Library (libpthread,
-lpthread)</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">pthread.h</a>></code></p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">pthread_rwlock_rdlock</code>(<var class="Fa" style="white-space: nowrap;">pthread_rwlock_t
*lock</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">pthread_rwlock_tryrdlock</code>(<var class="Fa" style="white-space: nowrap;">pthread_rwlock_t
*lock</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The
<a class="permalink" href="#pthread_rwlock_rdlock"><code class="Fn" id="pthread_rwlock_rdlock">pthread_rwlock_rdlock</code></a>()
function acquires a read lock on <var class="Fa">lock</var> provided that
<var class="Fa">lock</var> is not presently held for writing and no writer
threads are presently blocked on the lock. If the read lock cannot be
immediately acquired, the calling thread blocks until it can acquire the
lock.</p>
<p class="Pp" id="pthread_rwlock_tryrdlock">The
<a class="permalink" href="#pthread_rwlock_tryrdlock"><code class="Fn">pthread_rwlock_tryrdlock</code></a>()
function performs the same action, but does not block if the lock cannot be
immediately obtained (i.e., the lock is held for writing or there are
waiting writers).</p>
<p class="Pp" id="pthread_rwlock_unlock">A thread may hold multiple concurrent
read locks. If so,
<a class="permalink" href="#pthread_rwlock_unlock"><code class="Fn">pthread_rwlock_unlock</code></a>()
must be called once for each lock obtained.</p>
<p class="Pp">The results of acquiring a read lock while the calling thread
holds a write lock are undefined.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION
NOTES</a></h1>
<p class="Pp">To prevent writer starvation, writers are favored over
readers.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">If successful, the <code class="Fn">pthread_rwlock_rdlock</code>()
and <code class="Fn">pthread_rwlock_tryrdlock</code>() functions will return
zero. Otherwise an error number will be returned to indicate the error.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1>
<p class="Pp">The <code class="Fn">pthread_rwlock_tryrdlock</code>() function
will fail if:</p>
<dl class="Bl-tag">
<dt id="EBUSY">[<a class="permalink" href="#EBUSY"><code class="Er">EBUSY</code></a>]</dt>
<dd>The lock could not be acquired because a writer holds the lock or was
blocked on it.</dd>
</dl>
<p class="Pp">The <code class="Fn">pthread_rwlock_rdlock</code>() and
<code class="Fn">pthread_rwlock_tryrdlock</code>() functions may fail
if:</p>
<dl class="Bl-tag">
<dt id="EAGAIN">[<a class="permalink" href="#EAGAIN"><code class="Er">EAGAIN</code></a>]</dt>
<dd>The lock could not be acquired because the maximum number of read locks
against <var class="Fa">lock</var> has been exceeded.</dd>
<dt id="EDEADLK">[<a class="permalink" href="#EDEADLK"><code class="Er">EDEADLK</code></a>]</dt>
<dd>The current thread already owns <var class="Fa">lock</var> for
writing.</dd>
<dt id="EINVAL">[<a class="permalink" href="#EINVAL"><code class="Er">EINVAL</code></a>]</dt>
<dd>The value specified by <var class="Fa">lock</var> is invalid.</dd>
<dt id="ENOMEM">[<a class="permalink" href="#ENOMEM"><code class="Er">ENOMEM</code></a>]</dt>
<dd>Insufficient memory exists to initialize the lock (applies to statically
initialized locks only).</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">pthread_rwlock_init(3)</a>,
<a class="Xr">pthread_rwlock_trywrlock(3)</a>,
<a class="Xr">pthread_rwlock_unlock(3)</a>,
<a class="Xr">pthread_rwlock_wrlock(3)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1>
<p class="Pp">The <code class="Fn">pthread_rwlock_rdlock</code>() and
<code class="Fn">pthread_rwlock_tryrdlock</code>() functions are expected to
conform to <span class="St">Version 2 of the Single UNIX
Specification (“SUSv2”)</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Fn">pthread_rwlock_rdlock</code>() function first
appeared in <span class="Ux">FreeBSD 3.0</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">August 4, 1998</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
