Copy stable/9 to releng/9.3 as part of the 9.3-RELEASE cycle.

Approved by: re (implicit)
Sponsored by: The FreeBSD Foundation

MFC 252037: Document RA_RECURSED and RA_NOTRECURSED.

Copy head to stable/9 as part of 9.0-RELEASE release cycle.

Approved by: re (implicit)

Add manpages for rw_try_rlock() and rw_try_wlock() functions.

Implement soon-to-be-used rw_unlock() macro.

Add missing .El.

Clean up after previous revision.

Update rwlock(9) manpage adding missing bits about the rw_init_flags()
function, its options and explaining that recursion for writers can be
selectively enabled.

Reported by: rwatson, Skip Ford <skip at menantico dot com>

Add some cross references to locking.9 from related pages.

Allow threads to atomically release rw and sx locks while waiting for an
event. Locking primitives that support this (mtx, rw, and sx) now each
include their own foo_sleep() routine.
- Rename msleep() to _sleep() and change it's 'struct mtx' object to a
'struct lock_object' pointer. _sleep() uses the recently added
lc_unlock() and lc_lock() function pointers for the lock class of the
specified lock to release the lock while the thread is suspended.
- Add wrappers around _sleep() for mutexes (mtx_sleep()), rw locks
(rw_sleep()), and sx locks (sx_sleep()). msleep() still exists and
is now identical to mtx_sleep(), but it is deprecated.
- Rename SLEEPQ_MSLEEP to SLEEPQ_SLEEP.
- Rewrite much of sleep.9 to not be msleep(9) centric.
- Flesh out the 'RETURN VALUES' section in sleep.9 and add an 'ERRORS'
section.
- Add __nonnull(1) to _sleep() and msleep_spin() so that the compiler will
warn if you try to pass a NULL wait channel. The functions already have
a KASSERT to that effect.

Place mtx_destroy() and rw_destroy() right after mtx_init() and rw_init()
to match sx(9) and condvar(9).

- Sort rwlock functions similar to the order in mutex(9).
- Add a missing MLINK.

Update rwlock(9) for rw_wowned().

Revise markup.

Fix typo (s/writeer/writer/).

Document rw_try_upgrade() and rw_downgrade().

Various nits and fixups so that the text reads smoother in several places.
Also, more closely match the prototypes in sys/rwlock.h and add a BUGS
section.

Document read/write locks.

Reviewed by: jhb, ru