1.\" $OpenBSD: rwlock.9,v 1.8 2007/12/09 20:54:01 jmc 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: December 9 2007 $ 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.Sh DESCRIPTION 48The 49.Nm 50set of functions provides a multiple-reader, single-writer locking mechanism to 51ensure mutual exclusion between different processes. 52.Pp 53The 54.Fn rw_init 55function is used to initiate the lock pointed to by 56.Fa rwl . 57The 58.Fa name 59argument specifies the name of the lock, which is used as the wait message 60if the process needs to sleep. 61.Pp 62The 63.Fn rw_enter 64function acquires a lock. 65The 66.Fa flags 67argument specifies what kind of lock should be obtained and also 68modifies the operation. 69The possible flags are: 70.Pp 71.Bl -tag -offset indent -width RW_DOWNGRADEXXX -compact 72.It Dv RW_READ 73Acquire a shared lock. 74.It Dv RW_WRITE 75Acquire an exclusive lock. 76.It Dv RW_DOWNGRADE 77Safely release an exclusive lock and acquire a shared lock without 78letting other exclusive locks in between. 79.It Dv RW_INTR 80When waiting for a lock, allow signals to interrupt the sleep. 81.It Dv RW_NOSLEEP 82Do not wait for busy locks, fail with 83.Dv EBUSY 84instead. 85.It Dv RW_SLEEPFAIL 86Wait for busy locks, but do not obtain them, fail with 87.Dv EAGAIN 88instead. 89.El 90.Pp 91The 92.Fn rw_exit 93function is used to release a held lock. 94.Pp 95The 96.Fn rw_enter_read 97function acquires a read lock, sleeping if necessary. 98.Pp 99The 100.Fn rw_enter_write 101function acquires a write lock, sleeping if necessary. 102.Pp 103The 104.Fn rw_exit_read 105function releases a read lock. 106.Pp 107The 108.Fn rw_exit_write 109function releases a write lock. 110.Pp 111Read locks can be acquired while the write lock is not held, and may coexist in 112distinct processes at any time. 113A write lock, however, can only be acquired when there are no read locks held, 114granting exclusive access to a single process. 115.Sh SEE ALSO 116.Xr lockmgr 9 , 117.Xr mutex 9 , 118.Xr spl 9 119.Sh HISTORY 120The 121.Nm 122functions first appeared in 123.Ox 3.5 . 124.Sh AUTHORS 125The 126.Nm 127functions were written by 128.An Artur Grabowski 129.Aq art@openbsd.org . 130.Sh CAVEATS 131While it is safe to sleep with an rwlock held, they cannot 132be used in an interrupt handler as an rwlock is bound to a process. 133