diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index fe55977cd9e3..13e21f4cbae5 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -45,8 +45,7 @@ MAN= BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \ groupmember.9 \ ifnet.9 inittodr.9 intro.9 ithread.9 \ kernacc.9 kobj.9 kthread.9 ktr.9 \ - lockcount.9 lockdestroy.9 lockmgr.9 lockmgr_printinfo.9 \ - lockstatus.9 \ + lock.9 \ make_dev.9 malloc.9 mbchain.9 mbuf.9 mdchain.9 \ mi_switch.9 microseq.9 microtime.9 microuptime.9 \ module.9 mutex.9 \ @@ -251,6 +250,10 @@ MLINKS+=bus_generic_read_ivar.9 bus_generic_write_ivar.9 MLINKS+=ucred.9 crget.9 ucred.9 crhold.9 ucred.9 crfree.9 MLINKS+=ucred.9 crshared.9 ucred.9 crcopy.9 ucred.9 crdup.9 +MLINKS+= lock.9 lockinit.9 lock.9 lockdestroy.9 +MLINKS+= lock.9 lockcount.9 lock.9 lockmgr.9 +MLINKS+= lock.9 lockstatus.9 lock.9 lockmgr_printinfo.9 + MLINKS+=mbchain.9 mb_init.9 MLINKS+=mbchain.9 mb_initm.9 MLINKS+=mbchain.9 mb_done.9 diff --git a/share/man/man9/lock.9 b/share/man/man9/lock.9 index b48c6fe71374..c737a54d3a3d 100644 --- a/share/man/man9/lock.9 +++ b/share/man/man9/lock.9 @@ -1,139 +1,281 @@ -.\" Copyright (c) 2000 -.\" The Regents of the University of California. All rights reserved. .\" -.\" All rights reserved. +.\" Copyright (C) 2002 Chad David . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the +.\" notice(s), this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" -.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES -.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, -.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF -.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd October 24, 2000 +.Dd July 9, 2001 .Dt LOCK 9 .Os .Sh NAME .Nm lockinit , -.Nm lockmgr , +.Nm lockdestroy , .Nm lockcount , -.Nm lockstatus -.Nd kernel thread locking +.Nm lockmgr , +.Nm lockstatus , +.Nm lockmgr_printinfo +.Nd "lockmgr family of functions" .Sh SYNOPSIS .In sys/types.h -.In sys/lock.h +.In sys/lockmgr.h .Ft void .Fn lockinit "struct lock *lkp" "int prio" "char *wmesg" "int timo" "int flags" -.Ft int -.Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp" "struct thread *td" +.Ft void +.Fn lockdestroy "struct lock *lkp" .Ft int .Fn lockcount "struct lock *lkp" .Ft int +.Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp" "struct thread *td" +.Ft int .Fn lockstatus "struct lock *lkp" "struct thread *td" +.Ft void +.Fn lockmgr_printinfo "struct lock *lkp" .Sh DESCRIPTION -The function +The .Fn lockinit -is used to initialise a lock. -It is required if locks are used. -The function -.Fn lockmgr -is used to manage locks. -The function -.Fn lockcount -returns the number of shared lock holders on a lock. -The function -.Fn lockstatus -determines the status of a lock. +function is used to initialize a lock. +It must be called prior to any operation could be performed on a lock. +Its arguments are: +.Bl -tag -width ".Fa wmesg" +.It Fa lkp +A pointer to the lock to initialize. +.It Fa prio +The priority passed to +.Xr msleep 9 . +.It Fa wmesg +The lock message. +This is used for both debugging output and +.Xr msleep 9 . +.It Fa timo +The timeout value passed to +.Xr msleep 9 . +.It Fa flags +The flags the lock is to be initialized with. +.Bl -tag -width ".Dv LG_CANRECURSE" +.It Dv LK_NOWAIT +Do not sleep while acquiring the lock. +.It Dv LK_SLEEPFAIL +Fail after a sleep. +.It Dv LK_CANRECURSE +Allow recursive exclusive locks. +.It Dv LK_REENABLE +Re-enable the lock after a drain. +.It Dv LK_NOPAUSE +Disable the spinlock while acquiring the lock. +.It Dv LK_TIMELOCK +Use +.Fa timo +during a sleep; otherwise, 0 is used. +.El +.El .Pp -The following values are defined: +The +.Fn lockdestroy +function is used to destroy a lock, and while it is called in a number of +places in the kernel, it currently does nothing. +.Pp +The +.Fn lockcount +function returns a count of the number of exclusive locks and shared locks +held against the lock +.Fa lkp . +.Pp +The +.Fn lockmgr +function handles general locking functionality within the kernel, including +support for shared and exclusive locks, and recursion. +.Fn lockmgr +is also able to upgrade and downgrade locks. +.Pp +Its arguments are: +.Bl -tag -width ".Fa interlkp" +.It Fa lkp +A pointer to the lock to manipulate. +.It Fa flags +Flags indicating what action is to be taken. .Bl -tag -width ".Dv LK_EXCLUPGRADE" .It Dv LK_SHARED -get one of many possible shared locks. -If a thread holding an exclusive lock requests a shared lock, -the exclusive lock(s) will be downgraded to shared locks. +Acquire a shared lock. +If an exclusive lock is currently held, it will be downgraded. .It Dv LK_EXCLUSIVE -stop further shared locks, when they are cleared, -grant a pending upgrade if it exists, then grant an exclusive -lock. -Only one exclusive lock may exist at a time, except that -a thread holding an exclusive lock may get additional exclusive -locks if it explicitly sets the +Acquire an exclusive lock. +If an exclusive lock is already held, and .Dv LK_CANRECURSE -flag in the lock request, or if the -.Dv LK_CANRECURSE -flag was set when the lock was initialized. -.It Dv LK_UPGRADE -the thread must hold a shared lock that it wants to -have upgraded to an exclusive lock. -Other threads may get exclusive access to the resource between -the time that the upgrade is requested and the time that it is -granted. -.It Dv LK_EXCLUPGRADE -the thread must hold a shared lock that it wants to -have upgraded to an exclusive lock. -If the request succeeds, no other thread will have gotten -exclusive access to the resource between the time that the upgrade -is requested and the time that it is granted. -However, if another thread has already requested an upgrade, -the request will fail. +is not set, the system will +.Xr panic 9 . .It Dv LK_DOWNGRADE -the thread must hold an exclusive lock that it wants -to have downgraded to a shared lock. -If the thread holds multiple (recursive) exclusive locks, -they will all be downgraded to shared locks. +Downgrade exclusive lock to a shared lock. +Downgrading a shared lock is not permitted. +If an exclusive lock has been recursed, all references will be downgraded. +.It Dv LK_EXCLUPGRADE +Upgrade a shared lock to an exclusive lock. +Fails with +.Er EBUSY +if there is someone ahead of use waiting for an upgrade. +If this call fails, the shared lock is lost. +Attempt to upgrade an exclusive lock will cause a +.Xr panic 9 . +.It Dv LK_UPGRADE +Upgrade a shared lock to an exclusive lock. +If this call fails, the shared lock is lost. +Attempt to upgrade an exclusive lock will cause a +.Xr panic 9 . .It Dv LK_RELEASE -release one instance of a lock. +Release the lock. +Releasing a lock that is not held can cause a +.Xr panic 9 . .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 Dv LK_EXCLOTHER -return for -.Fn lockstatus . -Used when another thread holds the lock exclusively. +Wait for all activity on the lock to end, then mark it decommissioned. +This is used before freeing a lock that is part of a piece of memory that is +about to be freed. +(As documented in +.Aq Pa sys/lockmgr.h . ) +.It Dv LK_SLEEPFAIL +Fail if operation has slept. +.It Dv LK_NOWAIT +Do not allow the call to sleep. +This can be used to test the lock. +.It Dv LK_CANRECURSE +Allow recursion on an exclusive lock. +For every lock there must be a release. +.It Dv LK_INTERLOCK +Unlock the interlock (which should be locked already). .El +.It Fa interlkp +An interlock mutex for controlling group access to the lock. +If +.Dv LK_INTERLOCK +is specified, +.Fn lockmgr +assumes +.Fa interlkp +is currently owned and not recursed, and will return it unlocked. +See +.Xr mtx_assert 9 . +.It Fa td +A thread responsible for this call. +.Dv NULL +becomes +.Dv LK_KERNPROC . +.El +.Pp +The +.Fn lockstatus +function returns the status of the lock in relation to the +.Vt thread +passed to it. +Note that if +.Fa td +is +.Dv NULL +and an exclusive lock is held, +.Dv LK_EXCLUSIVE +will be returned. +.Pp +The +.Fn lockmgr_printinfo +function prints debugging information about the lock. +It is used primarily by +.Xr VOP_PRINT 9 +functions. .Sh RETURN VALUES -Successfully obtained locks return 0. -Locks will always succeed unless one of the following is true: +The +.Fn lockcount +function returns an integer greater than or equal to zero. +.Pp +The +.Fn lockmgr +function returns 0 on success and non-zero on failure. +.Pp +The +.Fn lockstatus +function returns: +.Bl -tag -width ".Dv LK_EXCLUSIVE" +.It Dv LK_EXCLUSIVE +An exclusive lock is held by the thread +.Fa td . +.It Dv LK_EXCLOTHER +An exclusive lock is held by someone other than the thread +.Fa td . +.It Dv LK_SHARED +A shared lock is held. +.It Li 0 +The lock is not held by anyone. +.El +.Sh ERRORS +.Fn lockmgr +fails if: +.Bl -tag -width Er +.It Bq Er EBUSY .Dv LK_FORCEUPGRADE -is requested and some other thread has already -requested a lock upgrade; returns -.Er EBUSY . -.Dv LK_WAIT -is set and a sleep would be required; returns -.Er EBUSY . +was requested and another thread had already requested a lock upgrade. +.It Bq Er EBUSY +.Dv LK_NOWAIT +was set, and a sleep would have been required. +.It Bq Er ENOLCK .Dv LK_SLEEPFAIL -is set and a sleep was done; returns -.Er ENOLCK . +was set and +.Fn lockmgr +did sleep. +.It Bq Er EINTR .Dv PCATCH -is set in lock priority and a signal arrives; returns -either -.Er EINTR -or +was set in the lock priority, and a signal was delivered during a sleep. +Note the .Er ERESTART -if system calls is to be restarted. -Non-null lock timeout and timeout expires; returns -.Er EWOULDBLOCK . -A failed lock attempt always returns a non-zero error value. -No lock is held after an error return (in particular, a failed -.Dv LK_UPGRADE -or -.Dv LK_FORCEUPGRADE -will have released its shared -access lock). +error below. +.It Bq Er ERESTART +.Dv PCATCH +was set in the lock priority, a signal was delivered during a sleep, +and the system call is to be restarted. +.It Bq Er EWOULDBLOCK +a non-zero timeout was given, and the timeout expired. +.El +.Sh LOCKS +If +.Dv LK_INTERLOCK +is passed in the +.Fa flags +argument to +.Fn lockmgr , +the +.Fa interlkp +must be held prior to calling +.Fn lockmgr , +and will be returned unlocked. +.Pp +Upgrade attempts that fail result in the loss of the lock that +is currently held. +Also, it is invalid to upgrade an +exclusive lock, and a +.Xr panic 9 +will be the result of trying. +.Sh SEE ALSO +.Xr msleep 9 , +.Xr mtx_assert 9 , +.Xr panic 9 , +.Xr VOP_PRINT 9 +.Sh AUTHORS +This man page was written by +.An Chad David Aq davidc@acns.ab.ca . diff --git a/share/man/man9/lockcount.9 b/share/man/man9/lockcount.9 deleted file mode 100644 index 06e101d5109f..000000000000 --- a/share/man/man9/lockcount.9 +++ /dev/null @@ -1,61 +0,0 @@ -.\" -.\" Copyright (C) 2001 Chad David . All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice(s), this list of conditions and the following disclaimer as -.\" the first lines of this file unmodified other than the possible -.\" addition of one or more copyright notices. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice(s), this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY -.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY -.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -.\" DAMAGE. -.\" -.\" $FreeBSD$ -.\" -.Dd July 9, 2001 -.Dt LOCKCOUNT 9 -.Os -.Sh NAME -.Nm lockcount -.Nd "returns the reference count of a lock" -.Sh SYNOPSIS -.In sys/types.h -.In sys/lockmgr.h -.Ft int -.Fn lockcount "struct lock *lkp" -.Sh DESCRIPTION -The -.Fn lockcount -function returns the reference count of the lock. -The reference -count is the sum of exclusive locks and shared locks. -.Pp -Its arguments are: -.Bl -tag -width ".Fa lkp" -.It Fa lkp -The lock to return the reference count on. -.El -.Sh RETURN VALUES -An integer greater than or equal to zero. -.Sh SEE ALSO -.Xr lockdestroy 9 , -.Xr lockmgr 9 , -.Xr lockmgr_printinfo 9 , -.Xr lockstatus 9 -.Sh AUTHORS -This man page was written by -.An Chad David Aq davidc@acns.ab.ca . diff --git a/share/man/man9/lockdestroy.9 b/share/man/man9/lockdestroy.9 deleted file mode 100644 index 005e15989250..000000000000 --- a/share/man/man9/lockdestroy.9 +++ /dev/null @@ -1,58 +0,0 @@ -.\" -.\" Copyright (C) 2001 Chad David . All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice(s), this list of conditions and the following disclaimer as -.\" the first lines of this file unmodified other than the possible -.\" addition of one or more copyright notices. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice(s), this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY -.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY -.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -.\" DAMAGE. -.\" -.\" $FreeBSD$ -.\" -.Dd July 9, 2001 -.Dt LOCKDESTROY 9 -.Os -.Sh NAME -.Nm lockdestroy -.Nd "destroys a lock" -.Sh SYNOPSIS -.In sys/param.h -.In sys/lockmgr.h -.Ft void -.Fn lockdestroy "struct lock *lkp" -.Sh DESCRIPTION -The -.Fn lockdestroy -function destroys the given lock. -(Currently is does nothing!) -.Pp -Its argument is: -.Bl -tag -width ".Fa lkp" -.It Fa lkp -The lock to destroy. -.El -.Sh SEE ALSO -.Xr lockcount 9 , -.Xr lockmgr 9 , -.Xr lockmgr_printinfo 9 , -.Xr lockstatus 9 -.Sh AUTHORS -This man page was written by -.An Chad David Aq davidc@acns.ab.ca . diff --git a/share/man/man9/lockmgr.9 b/share/man/man9/lockmgr.9 deleted file mode 100644 index bc7c65ba836a..000000000000 --- a/share/man/man9/lockmgr.9 +++ /dev/null @@ -1,151 +0,0 @@ -.\" -.\" Copyright (C) 2001 Chad David . All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice(s), this list of conditions and the following disclaimer as -.\" the first lines of this file unmodified other than the possible -.\" addition of one or more copyright notices. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice(s), this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY -.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY -.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -.\" DAMAGE. -.\" -.\" $FreeBSD$ -.\" -.Dd July 9, 2001 -.Dt LOCKMGR 9 -.Os -.Sh NAME -.Nm lockmgr -.Nd "acquires, releases and updates locks" -.Sh SYNOPSIS -.In sys/types.h -.In sys/lockmgr.h -.Ft int -.Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp" "struct thread *td" -.Sh DESCRIPTION -The -.Fn lockmgr -function handles general locking functionality within the kernel, including -support for shared and exclusive locks, and recursion. -Locks can also be upgraded and downgraded. -.Pp -Its arguments are: -.Bl -tag -width ".Fa interlkp" -.It Fa lkp -A pointer to the lock to manipulate. -.It Fa flags -Flags indicating what action is to be taken. -.Bl -tag -width ".Dv LK_EXCLUPGRADE" -.It Dv LK_SHARED -Acquire a shared lock. -If we currently hold an exclusive lock it will be downgraded. -.It Dv LK_EXCLUSIVE -Acquire an exclusive lock. -If we already hold an exclusive lock and -.Dv LK_CANRECURSE -is not set we will panic. -.It Dv LK_DOWNGRADE -Downgrade our exclusive lock to a shared lock. -Downgrading a shared lock is not valid. -If the exclusive lock has been recursed, all references will be downgraded. -.It Dv LK_EXCLUPGRADE -Upgrade our lock to an exclusive lock. -Will fail with -.Er EBUSY -if there is someone ahead of use waiting for an upgrade. -If this call fails we loose our shared lock. -Upgrading an exclusive lock will cause a panic. -.It Dv LK_UPGRADE -Upgrades our lock to an exclusive lock. -If this call fails we loose -our shared lock. -Upgrading an exclusive lock will cause a panic. -.It Dv LK_RELEASE -Release the lock. -Releasing a lock that you do not hold can cause a panic. -.It Dv LK_DRAIN -Waits for all activity on the lock to end, and then marks it decommissioned. -This is used before freeing a lock that is part of a piece of memory that is -about to be freed. -(As documented in -.Pa sys/lockmgr.h . ) -.It Dv LK_SLEEPFAIL -If we had to sleep for the lock then fail. -.It Dv LK_NOWAIT -Do not allow the call to sleep. -This can be used to test the lock. -.It Dv LK_CANRECURSE -It is ok to recurse on an exclusive lock. -For every lock there must be a release. -.It Dv LK_INTERLOCK -Unlock the interlock, which is of course locked already. -.El -.It Fa interlkp -An interlock mutex for controlling group access to the lock. -If -.Dv LK_INTERLOCK -is specified, -.Fn lockmgr -assumes -.Fa interlkp -is currently owned and not recursed, and will return it unlocked. -See -.Xr mtx_assert 9 . -.It Fa td -The thread responsible for this call. -.Dv NULL -becomes -.Dv LK_KERNPROC . -.El -.Sh LOCKS -If -.Dv LK_INTERLOCK -is specified then -.Fa interlkp -must be held prior to calling -.Fn lockmgr -and will be returned unlocked. -.Pp -Upgrade attempts that fail result in the loss of the lock that -is currently held. -As well, it is not valid to upgrade an -exclusive lock, and a panic will be the result of trying. -.Sh RETURN VALUES -A value of 0 is returned on success. -.Sh ERRORS -.Bl -tag -width Er -.It Bq Er EBUSY -Either -.Dv LK_NOWAIT -was specified and -.Fn lockmgr -would have slept, or another thread was ahead of you in line for an exclusive -upgrade. -.It Bq Er ENOLCK -.Dv LK_SLEEP_FAIL -was set and we slept. -.El -.Sh SEE ALSO -.Xr lockcount 9 , -.Xr lockdestroy 9 , -.Xr lockmgr_printinfo 9 , -.Xr lockstatus 9 , -.Xr mutex 9 -.Sh AUTHORS -This man page was written by -.An Chad David Aq davidc@acns.ab.ca . diff --git a/share/man/man9/lockmgr_printinfo.9 b/share/man/man9/lockmgr_printinfo.9 deleted file mode 100644 index 6a3051a60f69..000000000000 --- a/share/man/man9/lockmgr_printinfo.9 +++ /dev/null @@ -1,60 +0,0 @@ -.\" -.\" Copyright (C) 2001 Chad David . All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice(s), this list of conditions and the following disclaimer as -.\" the first lines of this file unmodified other than the possible -.\" addition of one or more copyright notices. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice(s), this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY -.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY -.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -.\" DAMAGE. -.\" -.\" $FreeBSD$ -.\" -.Dd July 9, 2001 -.Dt LOCKMGR_PRINTINFO 9 -.Os -.Sh NAME -.Nm lockmgr_printinfo -.Nd "prints information about the lock" -.Sh SYNOPSIS -.In sys/types.h -.In sys/lockmgr.h -.Ft void -.Fn lockmgr_printinfo "struct lock *lkp" -.Sh DESCRIPTION -The -.Fn lockmgr_printinfo -function prints information about the lock including the lock -time and the wait count. -.Pp -Its argument is: -.Bl -tag -width ".Fa lkp" -.It Fa lkp -The lock to print. -.El -.Sh NOTES -This function seems to only exist for debugging purposes. -.Sh SEE ALSO -.Xr lockcount 9 , -.Xr lockdestroy 9 , -.Xr lockmgr 9 , -.Xr lockstatus 9 -.Sh AUTHORS -This man page was written by -.An Chad David Aq davidc@acns.ab.ca . diff --git a/share/man/man9/lockstatus.9 b/share/man/man9/lockstatus.9 deleted file mode 100644 index 8273784c60aa..000000000000 --- a/share/man/man9/lockstatus.9 +++ /dev/null @@ -1,83 +0,0 @@ -.\" -.\" Copyright (C) 2001 Chad David . All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice(s), this list of conditions and the following disclaimer as -.\" the first lines of this file unmodified other than the possible -.\" addition of one or more copyright notices. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice(s), this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY -.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY -.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -.\" DAMAGE. -.\" -.\" $FreeBSD$ -.\" -.Dd July 9, 2001 -.Dt LOCKSTATUS 9 -.Os -.Sh NAME -.Nm lockstatus -.Nd "returns the lock status" -.Sh SYNOPSIS -.In sys/types.h -.In sys/lockmgr.h -.Ft int -.Fn lockstatus "struct lock *lkp" "struct thread *td" -.Sh DESCRIPTION -The -.Fn lockstatus -function returns the status of the lock in relation to the -.Vt thread -passed to it. -.Pp -Its arguments are: -.Bl -tag -width ".Fa lkp" -.It Fa lkp -The lock to return the status of. -.It Fa td -The thread to check any exclusive locks against. -If -.Fa td -is -.Dv NULL -and an exclusive lock is held, -.Dv LK_EXCLUSIVE -is returned. -.El -.Sh RETURN VALUES -.Bl -tag -width ".Dv LK_EXCLUSIVE" -.It Dv LK_EXCLUSIVE -An exclusive lock is held by the thread -.Fa td -passed in. -.It Dv LK_EXCLOTHER -An exclusive lock is held by someone other then the thread -.Fa td -passed in. -.It Dv LK_SHARED -A shared lock is held. -.It 0 -The lock is not held by anyone. -.El -.Sh SEE ALSO -.Xr lockcount 9 , -.Xr lockdestroy 9 , -.Xr lockmgr 9 , -.Xr lockmgr_printinfo 9 -.Sh AUTHORS -This man page was written by -.An Chad David Aq davidc@acns.ab.ca .