jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: pthread_rwlock_init.3,v 1.12 2025/07/08 02:23:49 jsg 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_init.3,v 1.2 1999/08/28 00:03:09 peter Exp $
27.\" $FreeBSD: pthread_rwlock_destroy.3,v 1.3 1999/08/28 00:03:09 peter Exp $
28.\" $FreeBSD: pthread_rwlock_rdlock.3,v 1.2 1999/08/28 00:03:09 peter Exp $
29.\" $FreeBSD: pthread_rwlock_wrlock.3,v 1.2 1999/08/28 00:03:10 peter Exp $
30.\" $FreeBSD: pthread_rwlock_unlock.3,v 1.2 1999/08/28 00:03:10 peter Exp $
31.\"
32.Dd $Mdocdate: July 8 2025 $
33.Dt PTHREAD_RWLOCK_INIT 3
34.Os
35.Sh NAME
36.Nm pthread_rwlock_init ,
37.Nm pthread_rwlock_destroy ,
38.Nm pthread_rwlock_rdlock ,
39.Nm pthread_rwlock_timedrdlock ,
40.Nm pthread_rwlock_tryrdlock ,
41.Nm pthread_rwlock_wrlock ,
42.Nm pthread_rwlock_timedwrlock ,
43.Nm pthread_rwlock_trywrlock ,
44.Nm pthread_rwlock_unlock
45.Nd operations on read/write locks
46.Sh SYNOPSIS
47.Lb libpthread
48.In pthread.h
49.Ft int
50.Fo pthread_rwlock_init
51.Fa "pthread_rwlock_t *lock"
52.Fa "const pthread_rwlockattr_t *attr"
53.Fc
54.Ft int
55.Fo pthread_rwlock_destroy
56.Fa "pthread_rwlock_t *lock"
57.Fc
58.Ft int
59.Fo pthread_rwlock_rdlock
60.Fa "pthread_rwlock_t *lock"
61.Fc
62.Ft int
63.Fo pthread_rwlock_timedrdlock
64.Fa "pthread_rwlock_t *lock"
65.Fa "const struct timespec *abstime"
66.Fc
67.Ft int
68.Fo pthread_rwlock_tryrdlock
69.Fa "pthread_rwlock_t *lock"
70.Fc
71.Ft int
72.Fo pthread_rwlock_wrlock
73.Fa "pthread_rwlock_t *lock"
74.Fc
75.Ft int
76.Fo pthread_rwlock_timedwrlock
77.Fa "pthread_rwlock_t *lock"
78.Fa "const struct timespec *abstime"
79.Fc
80.Ft int
81.Fo pthread_rwlock_trywrlock
82.Fa "pthread_rwlock_t *lock"
83.Fc
84.Ft int
85.Fo pthread_rwlock_unlock
86.Fa "pthread_rwlock_t *lock"
87.Fc
88.Sh DESCRIPTION
89The
90.Fn pthread_rwlock_init
91function initializes a read/write lock, with attributes
92specified by
93.Fa attr .
94If
95.Fa attr
96is NULL, the default read/write lock attributes are used.
97The results of calling
98.Fn pthread_rwlock_init
99with an already initialized lock are undefined.
100.Pp
101The
102.Fn pthread_rwlock_destroy
103function destroys a read/write lock previously created with
104.Fn pthread_rwlock_init .
105.Pp
106The
107.Fn pthread_rwlock_rdlock
108function acquires a read lock on
109.Fa lock
110provided that
111.Fa lock
112is not presently held for writing and no writer threads are
113presently blocked on the lock.
114If the read lock cannot be immediately acquired,
115the calling thread blocks until it can acquire the lock.
116.Pp
117The
118.Fn pthread_rwlock_wrlock
119function blocks until a write lock can be acquired against
120.Fa lock .
121.Pp
122The
123.Fn pthread_rwlock_timedrdlock
124and
125.Fn pthread_rwlock_timedwrlock
126functions perform the same action,
127but will not wait beyond
128.Fa abstime
129to obtain the lock before returning.
130.Pp
131The
132.Fn pthread_rwlock_tryrdlock
133and
134.Fn pthread_rwlock_trywrlock
135functions perform the same action
136but do not block if the lock cannot be immediately obtained.
137.Pp
138The
139.Fn pthread_rwlock_unlock
140function releases the read/write lock previously obtained.
141.Pp
142A thread may hold multiple concurrent read locks.
143If so,
144.Fn pthread_rwlock_unlock
145must be called once for each lock obtained.
146.Sh RETURN VALUES
147If successful, these functions return zero.
148Otherwise an error number will be returned to indicate the error.
149.Sh ERRORS
150.Fn pthread_rwlock_init
151fails if:
152.Bl -tag -width Er
153.It Bq Er EAGAIN
154The system lacked the necessary resources (other than memory) to
155initialize the lock.
156.It Bq Er ENOMEM
157Insufficient memory exists to initialize the lock.
158.It Bq Er EPERM
159The caller does not have sufficient privilege to perform the
160operation.
161.It Bq Er EBUSY
162The system has detected an attempt to re-initialize the object
163referenced by
164.Fa lock ,
165a previously initialized but not yet destroyed read/write lock.
166.It Bq Er EINVAL
167The value specified by
168.Fa attr
169is invalid.
170.El
171.Pp
172Other functions fail if:
173.Bl -tag -width Er
174.It Bq Er EINVAL
175The value specified by
176.Fa lock
177is invalid.
178.It Bq Er ENOMEM
179Insufficient memory exists to initialize the lock (applies to
180statically initialized locks only).
181.El
182.Pp
183.Fn pthread_rwlock_destroy
184fails if:
185.Bl -tag -width Er
186.It Bq Er EBUSY
187The system has detected an attempt to destroy the object referenced by
188.Fa lock
189while it is locked.
190.El
191.Pp
192.Fn pthread_rwlock_tryrdlock
193and
194.Fn pthread_rwlock_trywrlock
195fail if:
196.Bl -tag -width Er
197.It Bq Er EBUSY
198The lock could not be acquired without blocking.
199.El
200.Pp
201.Fn pthread_rwlock_timedrdlock
202and
203.Fn pthread_rwlock_timedwrlock
204fail if:
205.Bl -tag -width Er
206.It Bq Er ETIMEDOUT
207The time specified by
208.Fa abstime
209was reached before the lock could be obtained.
210.El
211.Pp
212The
213.Fn pthread_rwlock_rdlock ,
214.Fn pthread_rwlock_timedrdlock ,
215and
216.Fn pthread_rwlock_tryrdlock
217functions fail if:
218.Bl -tag -width Er
219.It Bq Er EAGAIN
220The lock could not be acquired because the maximum number of read locks
221against
222.Fa lock
223has been exceeded.
224.It Bq Er EDEADLK
225The current thread already owns
226.Fa lock
227for writing.
228.El
229.Pp
230The
231.Fn pthread_rwlock_wrlock ,
232.Fn pthread_rwlock_timedwrlock ,
233and
234.Fn pthread_rwlock_trywrlock
235functions fail if:
236.Bl -tag -width Er
237.It Bq Er EDEADLK
238The calling thread already owns the read/write lock (for reading
239or writing).
240.El
241.Pp
242The
243.Fn pthread_rwlock_unlock
244fails if:
245.Bl -tag -width Er
246.It Bq Er EPERM
247The current thread does not own the read/write lock.
248.El
249.Sh SEE ALSO
250.Xr pthread_rwlockattr_init 3 ,
251.Xr pthreads 3
252.Sh STANDARDS
253These functions are expected to conform to
254.St -susv2 .
255.Sh HISTORY
256.Fn pthread_rwlock_init ,
257.Fn pthread_rwlock_destroy ,
258.Fn pthread_rwlock_rdlock ,
259.Fn pthread_rwlock_tryrdlock ,
260.Fn pthread_rwlock_wrlock ,
261.Fn pthread_rwlock_trywrlock ,
262and
263.Fn pthread_rwlock_unlock
264have been available since
265.Ox 2.5 ,
266and
267.Fn pthread_rwlock_timedrdlock
268and
269.Fn pthread_rwlock_timedwrlock
270since
271.Ox 4.8 .
272.Sh BUGS
273The PTHREAD_PROCESS_SHARED attribute is not supported.