Document the rwlock() API, okay deraadt@

2 files changed, 89 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 1967a0b27e8..85fce92c72d 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.111 2006/01/18 14:51:42 mickey Exp $
+#	$OpenBSD: Makefile,v 1.112 2006/04/20 20:32:31 pedro Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -19,7 +19,7 @@ MAN=	altq.9 audio.9 autoconf.9 boot.9 buffercache.9 bus_dma.9 bus_space.9 \
 	mountroothook_establish.9 mutex.9 namei.9 \
 	panic.9 pci_conf_read.9 pci_intr_map.9 pfind.9 physio.9 pmap.9 \
 	pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
-	radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 \
+	radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 rwlock.9 \
 	shutdownhook_establish.9 sleep.9 spl.9 startuphook_establish.9 \
 	style.9 syscall.9 systrace.9 sysctl_int.9 \
 	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 vfs_cache.9 \
@@ -213,6 +213,8 @@ MLINKS+=rssadapt.9 ieee80211_rssadapt_choose.9 \
 	rssadapt.9 ieee80211_rssadapt_lower_rate.9 \
 	rssadapt.9 ieee80211_rssadapt_raise_rate.9 \
 	rssadapt.9 ieee80211_rssadapt_updatestats.9
+MLINKS+=rwlock.9 rw_init.9 rwlock.9 rw_enter_read.9 rwlock.9 rw_enter_write.9 \
+	rwlock.9 rw_exit_read.9 rwlock.9 rw_exit_write.9
 MLINKS+=pci_conf_read.9 pci_conf_write.9 pci_conf_read.9 pci_make_tag.9 \
 	pci_conf_read.9 pci_decompose_tag.9
 MLINKS+=pci_intr_map.9 pci_intr_string.9 pci_intr_map.9 pci_intr_line.9 \
diff --git a/share/man/man9/rwlock.9 b/share/man/man9/rwlock.9
new file mode 100644
index 00000000000..bbbbbd080ee
--- /dev/null
+++ b/share/man/man9/rwlock.9
@@ -0,0 +1,85 @@
+.\" $OpenBSD: rwlock.9,v 1.1 2006/04/20 20:32:31 pedro Exp $
+.\"
+.\" Copyright (c) 2006 Pedro Martelletto <pedro@openbsd.org>
+.\" All rights reserved.
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd April 19, 2006
+.Dt RWLOCK 9
+.Os
+.Sh NAME
+.Nm rwlock ,
+.Nm rw_init ,
+.Nm rw_enter_read ,
+.Nm rw_enter_write ,
+.Nm rw_exit_read ,
+.Nm rw_exit_write
+.Nd interface to read/write locks
+.Sh SYNOPSIS
+.Fd #include <sys/rwlock.h>
+.Ft void
+.Fn rw_init "struct rwlock *rwl"
+.Ft void
+.Fn rw_enter_read "struct rwlock *rwl"
+.Ft void
+.Fn rw_enter_write "struct rwlock *rwl"
+.Ft void
+.Fn rw_exit_read "struct rwlock *rwl"
+.Ft void
+.Fn rw_exit_write "struct rwlock *rwl"
+.Sh DESCRIPTION
+The
+.Nm
+set of functions provides a multiple-reader, single-writer locking mechanism to
+ensure mutual exclusion between different processes.
+.Pp
+The
+.Fn rw_init
+function is used to initiate the lock pointed to by
+.Fa rwl .
+.Pp
+The
+.Fn rw_enter_read
+function acquires a read lock, sleeping if necessary.
+.Pp
+The
+.Fn rw_enter_write
+function acquires a write lock, sleeping if necessary.
+.Pp
+The
+.Fn rw_exit_read
+function releases a read lock.
+.Pp
+The
+.Fn rw_exit_write
+function releases a write lock.
+.Pp
+Read locks can be acquired while the write lock is not held, and may coexist in
+distinct processes at any time.
+A write lock, however, can only be acquired when there are no read locks held,
+granting exclusive access to a single process.
+.Sh SEE ALSO
+.Xr lockmgr 9 ,
+.Xr spl 9
+.Sh HISTORY
+The
+.Nm
+functions first appeared in
+.Ox 3.5 .
+.Sh AUTHORS
+The
+.Nm
+functions were written by
+.An Artur Grabowski
+.Aq art@openbsd.org .