1.\" $OpenBSD: pthread_rwlock_rdlock.3,v 1.10 2010/05/03 20:43:24 jmc Exp $
2.\" Copyright (c) 1998 Alex Nash
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD: pthread_rwlock_rdlock.3,v 1.2 1999/08/28 00:03:09 peter Exp $
27.\"
28.Dd $Mdocdate: May 3 2010 $
29.Dt PTHREAD_RWLOCK_RDLOCK 3
30.Os
31.Sh NAME
32.Nm pthread_rwlock_rdlock ,
33.Nm pthread_rwlock_timedrdlock ,
34.Nm pthread_rwlock_tryrdlock
35.Nd acquire a read/write lock for reading
36.Sh SYNOPSIS
37.Fd #include <pthread.h>
38.Ft int
39.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
40.Ft int
41.Fn pthread_rwlock_timedrdlock "pthread_rwlock_t *lock" "const struct timespec *abstime"
42.Ft int
43.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
44.Sh DESCRIPTION
45The
46.Fn pthread_rwlock_rdlock
47function acquires a read lock on
48.Fa lock
49provided that
50.Fa lock
51is not presently held for writing and no writer threads are
52presently blocked on the lock.
53If the read lock cannot be immediately acquired,
54the calling thread blocks until it can acquire the lock.
55.Pp
56The
57.Fn pthread_rwlock_timedrdlock
58function performs the same action,
59but will not wait beyond
60.Fa abstime
61to obtain the lock before returning.
62.Pp
63The
64.Fn pthread_rwlock_tryrdlock
65function performs the same action as
66.Fn pthread_rwlock_rdlock ,
67but does not block if the lock cannot be immediately obtained
68(i.e., the lock is held for writing or there are writers waiting).
69.Pp
70A thread may hold multiple concurrent read locks.
71If so,
72.Fn pthread_rwlock_unlock
73must be called once for each lock obtained.
74.Pp
75The results of acquiring a read lock while the calling thread holds
76a write lock are undefined.
77.Sh IMPLEMENTATION NOTES
78To prevent writer starvation, writers are favored over readers.
79.Sh RETURN VALUES
80If successful, the
81.Fn pthread_rwlock_rdlock ,
82.Fn pthread_rwlock_timedrdlock ,
83and
84.Fn pthread_rwlock_tryrdlock
85functions will return zero.
86Otherwise an error number will be returned to indicate the error.
87.Sh ERRORS
88The
89.Fn pthread_rwlock_tryrdlock
90function will fail if:
91.Bl -tag -width Er
92.It Bq Er EBUSY
93The lock could not be acquired because a writer holds the lock or
94was blocked on it.
95.El
96.Pp
97The
98.Fn pthread_rwlock_timedrdlock
99function will fail if:
100.Bl -tag -width Er
101.It Bq Er ETIMEDOUT
102The time specified by
103.Fa abstime
104was reached before the lock could be obtained.
105.El
106.Pp
107The
108.Fn pthread_rwlock_rdlock ,
109.Fn pthread_rwlock_timedrdlock ,
110and
111.Fn pthread_rwlock_tryrdlock
112functions may fail if:
113.Bl -tag -width Er
114.It Bq Er EAGAIN
115The lock could not be acquired because the maximum number of read locks
116against
117.Fa lock
118has been exceeded.
119.It Bq Er EDEADLK
120The current thread already owns
121.Fa lock
122for writing.
123.It Bq Er EINVAL
124The value specified by
125.Fa lock
126is invalid.
127.It Bq Er ENOMEM
128Insufficient memory exists to initialize the lock (applies to
129statically initialized locks only).
130.El
131.Sh SEE ALSO
132.Xr pthread_rwlock_init 3 ,
133.Xr pthread_rwlock_trywrlock 3 ,
134.Xr pthread_rwlock_unlock 3 ,
135.Xr pthread_rwlock_wrlock 3
136.Sh STANDARDS
137The
138.Fn pthread_rwlock_rdlock ,
139.Fn pthread_rwlock_timedrdlock ,
140and
141.Fn pthread_rwlock_tryrdlock
142functions are expected to conform to
143.St -susv2 .
144.Sh HISTORY
145The
146.Fn pthread_rwlock_rdlock
147function first appeared in
148.Fx 3.0
149and
150.Ox 2.5 .
151The
152.Fn pthread_rwlock_timedrdlock
153function first appeared in
154.Ox 4.8 .
155