[src/trunk]: src/share/man/man9 Bump date for last. Minor English fixes. Us...

[snj <snj%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/b3a85429ca22
branches:  trunk
changeset: 566912:b3a85429ca22
user:      snj <snj%NetBSD.org@localhost>
date:      Mon May 24 03:26:34 2004 +0000

description:
Bump date for last.  Minor English fixes.  Use Dq.  Sprinkle some Dv.

diffstat:

 share/man/man9/lock.9 |  95 +++++++++++++++++++++++++++++---------------------
 1 files changed, 55 insertions(+), 40 deletions(-)

diffs (206 lines):

diff -r ae2603636b51 -r b3a85429ca22 share/man/man9/lock.9
--- a/share/man/man9/lock.9     Mon May 24 03:09:48 2004 +0000
+++ b/share/man/man9/lock.9     Mon May 24 03:26:34 2004 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: lock.9,v 1.19 2004/05/22 18:00:30 yamt Exp $
+.\"     $NetBSD: lock.9,v 1.20 2004/05/24 03:26:34 snj Exp $
 .\"
 .\" Copyright (c) 2000 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -31,7 +31,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 23, 2000
+.Dd May 22, 2004
 .Dt LOCK 9
 .Os
 .Sh NAME
@@ -121,7 +121,8 @@
 .Fa slock
 is initialised to the unlocked state.
 A statically allocated simplelock also can be initialised with the
-macro SIMPLELOCK_INITIALIZER.
+macro
+.Dv SIMPLELOCK_INITIALIZER .
 The effect is the same as the dynamic initialisation by a call to
 simple_lock_init.
 For example,
@@ -133,11 +134,12 @@
 is locked.
 If the simplelock is held then execution will spin until the simplelock
 is acquired.
-Care must be taken that the calling thread does not already hold
+Care must be taken to ensure that the calling thread does not already hold
 the simplelock.
 In this case, the simplelock can never be acquired.
-If kernel option LOCKDEBUG is enabled, a "locking against myself" panic
-will occur.
+If kernel option LOCKDEBUG is enabled, a
+.Dq locking against myself
+panic will occur.
 .It Fn simple_lock_try "slock"
 Try to acquire the simplelock
 .Fa slock
@@ -191,11 +193,11 @@
 the lock.
 Valid lock flags are:
 .Bl -tag -width compact
-.It LK_NOWAIT
+.It Dv LK_NOWAIT
 Threads should not sleep when attempting to acquire the lock.
-.It LK_SLEEPFAIL
+.It Dv LK_SLEEPFAIL
 Threads should sleep, then return failure when acquiring the lock.
-.It LK_CANRECURSE
+.It Dv LK_CANRECURSE
 Threads can acquire the lock recursively.
 .El
 .El
@@ -207,38 +209,44 @@
 The lock.
 .It Fa slock
 Simplelock interlock.
-If the flag LK_INTERLOCK is set in
+If the flag
+.Dv LK_INTERLOCK
+is set in
 .Fa flags ,
 .Fa slock
 is a simplelock held by the caller.
 When the lock
 .Fa lock
 is acquired, the simplelock is released.
-If the flag LK_INTERLOCK is not set,
+If the flag
+.Dv LK_INTERLOCK
+is not set,
 .Fa slock
 is ignored.
 .It Fa flags
 Flags to specify the lock request type.
 In addition to the flags specified above, the following flags are valid:
 .Bl -tag -width compact
-.It LK_SHARED
+.It Dv LK_SHARED
 Get one of many possible shared-access locks.
 If a thread holding an exclusive-access lock requests a shared-access
 lock, the exclusive-access lock is downgraded to a shared-access lock.
-.It LK_EXCLUSIVE
+.It Dv LK_EXCLUSIVE
 Stop further shared-access locks, when they are cleared, grant a
 pending upgrade if it exists, then grant an exclusive-access lock.
 Only one exclusive-access lock may exist at a time, except that a
 thread holding an exclusive-access lock may get additional
-exclusive-access locks if it explicitly sets the LK_CANRECURSE flag in
-the lock request, or if the LK_CANRECURSE flag was set when the lock
-was initialised.
-.It LK_UPGRADE
+exclusive-access locks if it explicitly sets the
+.Dv LK_CANRECURSE
+flag in the lock request, or if the
+.Dv LK_CANRECURSE
+flag was set when the lock was initialised.
+.It Dv LK_UPGRADE
 The thread must hold a shared-access lock that it wants to have
 upgraded to an exclusive-access lock.
 Other threads may get exclusive access to the protected resource between
 the time that the upgrade is requested and the time that it is granted.
-.It LK_EXCLUPGRADE
+.It Dv LK_EXCLUPGRADE
 The thread must hold a shared-access lock that it wants to have
 upgraded to an exclusive-access lock.
 If the request succeeds, no other threads will have acquired exclusive
@@ -246,28 +254,29 @@
 requested and the time that it is granted.
 However, if another thread has already requested an upgrade, the request
 will fail.
-.It LK_DOWNGRADE
+.It Dv LK_DOWNGRADE
 The thread must hold an exclusive-access lock that it wants to have
 downgraded to a shared-access lock.
 If the thread holds multiple (recursive) exclusive-access locks, they
 will all be downgraded to shared-access locks.
-.It LK_RELEASE
+.It Dv LK_RELEASE
 Release one instance of a lock.
-.It LK_DRAIN
+.It Dv LK_DRAIN
 Wait for all activity on the lock to end, then mark it decommissioned.
 This feature is used before freeing a lock that is part of a piece of
 memory that is about to be freed.
-.It LK_REENABLE
+.It Dv LK_REENABLE
 Lock is to be re-enabled after drain.
-The LK_REENABLE flag may be set only at the release of a lock obtained
-by a drain.
-.It LK_SETRECURSE
+The
+.Dv LK_REENABLE
+flag may be set only at the release of a lock obtained by a drain.
+.It Dv LK_SETRECURSE
 Other locks while we have it OK.
-.It LK_RECURSEFAIL
+.It Dv LK_RECURSEFAIL
 Attempt at recursive lock fails.
-.It LK_SPIN
+.It Dv LK_SPIN
 Lock spins instead of sleeping.
-.It LK_INTERLOCK
+.It Dv LK_INTERLOCK
 Unlock the simplelock
 .Fa slock
 when the lock is acquired.
@@ -276,13 +285,13 @@
 .It Fn lockstatus "lock"
 Determine the status of lock
 .Fa lock .
-Returns one of the followings:
+Returns one of the following:
 .Bl -tag -width compact
-.It LK_EXCLUSIVE
+.It Dv LK_EXCLUSIVE
 The current lwp or cpu holds an exclusive-access lock.
-.It LK_EXCLOTHER
+.It Dv LK_EXCLOTHER
 The other lwp or cpu holds an exclusive-access lock.
-.It LK_SHARED
+.It Dv LK_SHARED
 Someone holds shared-access lock.
 .It 0
 Not locked.
@@ -327,20 +336,26 @@
 Successfully acquired locks return 0.
 A failed lock attempt always returns a non-zero error value.
 No lock is held after an error return (in particular, a failed
-LK_UPGRADE or LK_FORCEUPGRADE will have released its shared-access lock).
+.Dv LK_UPGRADE
+or
+.Dv LK_FORCEUPGRADE
+will have released its shared-access lock).
 Locks will always succeed unless one of the following is true:
 .Bl -tag -width Er
 .It Bq Er EBUSY
-LK_FORCEUPGRADE is requested and some other thread has already
-requested a lock upgrade or LK_NOWAIT is set and a sleep would
-be required.
+.Dv LK_FORCEUPGRADE
+is requested and some other thread has already requested a lock upgrade or
+.Dv LK_NOWAIT
+is set and a sleep would be required.
 .It Bq Er ENOLCK
-LK_SLEEPFAIL is set and a sleep was done.
+.Dv LK_SLEEPFAIL
+is set and a sleep was done.
 .It Bq Er EINTR
-PCATCH is set in lock priority and a signal arrives to interrupt
-a system call.
+.Dv PCATCH
+is set in lock priority and a signal arrives to interrupt a system call.
 .It Bq Er ERESTART
-PCATCH is set in lock priority and a signal arrives so that
+.Dv PCATCH
+is set in lock priority and a signal arrives so that
 the system call is restarted.
 .It Bq Er EWOULDBLOCK
 Non-null lock timeout and timeout expires.