1.\" $OpenBSD: pthread_rwlock_rdlock.3,v 1.12 2019/02/13 23:54:10 mpi 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: February 13 2019 $
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.In 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 RETURN VALUES
78If successful, the
79.Fn pthread_rwlock_rdlock ,
80.Fn pthread_rwlock_timedrdlock ,
81and
82.Fn pthread_rwlock_tryrdlock
83functions will return zero.
84Otherwise an error number will be returned to indicate the error.
85.Sh ERRORS
86The
87.Fn pthread_rwlock_tryrdlock
88function will fail if:
89.Bl -tag -width Er
90.It Bq Er EBUSY
91The lock could not be acquired because a writer holds the lock or
92was blocked on it.
93.El
94.Pp
95The
96.Fn pthread_rwlock_timedrdlock
97function will fail if:
98.Bl -tag -width Er
99.It Bq Er ETIMEDOUT
100The time specified by
101.Fa abstime
102was reached before the lock could be obtained.
103.El
104.Pp
105The
106.Fn pthread_rwlock_rdlock ,
107.Fn pthread_rwlock_timedrdlock ,
108and
109.Fn pthread_rwlock_tryrdlock
110functions may fail if:
111.Bl -tag -width Er
112.It Bq Er EAGAIN
113The lock could not be acquired because the maximum number of read locks
114against
115.Fa lock
116has been exceeded.
117.It Bq Er EDEADLK
118The current thread already owns
119.Fa lock
120for writing.
121.It Bq Er EINVAL
122The value specified by
123.Fa lock
124is invalid.
125.It Bq Er ENOMEM
126Insufficient memory exists to initialize the lock (applies to
127statically initialized locks only).
128.El
129.Sh SEE ALSO
130.Xr pthread_rwlock_init 3 ,
131.Xr pthread_rwlock_trywrlock 3 ,
132.Xr pthread_rwlock_unlock 3 ,
133.Xr pthread_rwlock_wrlock 3
134.Sh STANDARDS
135The
136.Fn pthread_rwlock_rdlock ,
137.Fn pthread_rwlock_timedrdlock ,
138and
139.Fn pthread_rwlock_tryrdlock
140functions are expected to conform to
141.St -susv2 .
142.Sh HISTORY
143The
144.Fn pthread_rwlock_rdlock
145function first appeared in
146.Fx 3.0
147and
148.Ox 2.5 .
149The
150.Fn pthread_rwlock_timedrdlock
151function first appeared in
152.Ox 4.8 .
153