1.\" $OpenBSD: rwlock.9,v 1.9 2010/08/01 14:21:10 blambert Exp $ 2.\" 3.\" Copyright (c) 2006 Pedro Martelletto <pedro@ambientworks.net> 4.\" All rights reserved. 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: August 1 2010 $ 19.Dt RWLOCK 9 20.Os 21.Sh NAME 22.Nm rwlock , 23.Nm rw_init , 24.Nm rw_enter , 25.Nm rw_exit , 26.Nm rw_enter_read , 27.Nm rw_enter_write , 28.Nm rw_exit_read , 29.Nm rw_exit_write 30.Nd interface to read/write locks 31.Sh SYNOPSIS 32.Fd #include <sys/rwlock.h> 33.Ft void 34.Fn rw_init "struct rwlock *rwl" "const char *name" 35.Ft int 36.Fn rw_enter "struct rwlock *rwl" "int flags" 37.Ft void 38.Fn rw_exit "struct rwlock *rwl" 39.Ft void 40.Fn rw_enter_read "struct rwlock *rwl" 41.Ft void 42.Fn rw_enter_write "struct rwlock *rwl" 43.Ft void 44.Fn rw_exit_read "struct rwlock *rwl" 45.Ft void 46.Fn rw_exit_write "struct rwlock *rwl" 47.Ft void 48.Fn rw_assert_wrlock "struct rwlock *rwl" 49.Ft void 50.Fn rw_assert_rdlock "struct rwlock *rwl" 51.Ft void 52.Fn rw_assert_unlocked "struct rwlock *rwl" 53.Sh DESCRIPTION 54The 55.Nm 56set of functions provides a multiple-reader, single-writer locking mechanism to 57ensure mutual exclusion between different processes. 58.Pp 59The 60.Fn rw_init 61function is used to initiate the lock pointed to by 62.Fa rwl . 63The 64.Fa name 65argument specifies the name of the lock, which is used as the wait message 66if the process needs to sleep. 67.Pp 68The 69.Fn rw_enter 70function acquires a lock. 71The 72.Fa flags 73argument specifies what kind of lock should be obtained and also 74modifies the operation. 75The possible flags are: 76.Pp 77.Bl -tag -offset indent -width RW_DOWNGRADEXXX -compact 78.It Dv RW_READ 79Acquire a shared lock. 80.It Dv RW_WRITE 81Acquire an exclusive lock. 82.It Dv RW_DOWNGRADE 83Safely release an exclusive lock and acquire a shared lock without 84letting other exclusive locks in between. 85.It Dv RW_INTR 86When waiting for a lock, allow signals to interrupt the sleep. 87.It Dv RW_NOSLEEP 88Do not wait for busy locks, fail with 89.Dv EBUSY 90instead. 91.It Dv RW_SLEEPFAIL 92Wait for busy locks, but do not obtain them, fail with 93.Dv EAGAIN 94instead. 95.El 96.Pp 97The 98.Fn rw_exit 99function is used to release a held lock. 100.Pp 101The 102.Fn rw_enter_read 103function acquires a read lock, sleeping if necessary. 104.Pp 105The 106.Fn rw_enter_write 107function acquires a write lock, sleeping if necessary. 108.Pp 109The 110.Fn rw_exit_read 111function releases a read lock. 112.Pp 113The 114.Fn rw_exit_write 115function releases a write lock. 116.Pp 117Read locks can be acquired while the write lock is not held, and may coexist in 118distinct processes at any time. 119A write lock, however, can only be acquired when there are no read locks held, 120granting exclusive access to a single process. 121.Pp 122The 123.Fn rw_assert_wrlock , 124.Fn rw_assert_rdlock , 125and 126.Fn rw_assert_unlocked 127functions check the status 128.Fa rwl , 129panicking if it is not write-, read-, or unlocked, respectively. 130.Sh SEE ALSO 131.Xr lockmgr 9 , 132.Xr mutex 9 , 133.Xr spl 9 134.Sh HISTORY 135The 136.Nm 137functions first appeared in 138.Ox 3.5 . 139.Sh AUTHORS 140The 141.Nm 142functions were written by 143.An Artur Grabowski 144.Aq art@openbsd.org . 145.Sh CAVEATS 146While it is safe to sleep with an rwlock held, they cannot 147be used in an interrupt handler as an rwlock is bound to a process. 148