The Regents of the University of California. All rights reserved.
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.
2. Redistributions in binary form must reproduce the above copyright
notice, 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.
$FreeBSD: head/share/man/man9/lock.9 89203 2002-01-10 12:32:38Z ru $
.Dd October 24, 2000 .Dt LOCK 9 .Os .Sh NAME .Nm lockinit , .Nm lockmgr , .Nm lockcount , .Nm lockstatus .Nd kernel thread locking .Sh SYNOPSIS n sys/types.h n sys/lock.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 int .Fn lockcount "struct lock *lkp" .Ft int .Fn lockstatus "struct lock *lkp" "struct thread *td" .Sh DESCRIPTION The function .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.
p The following values are defined: l -tag -width ".Dv LK_EXCLUPGRADE" t 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. t 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 .Dv LK_CANRECURSE flag in the lock request, or if the .Dv LK_CANRECURSE flag was set when the lock was initialized. t 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. t 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. t 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. t Dv LK_RELEASE release one instance of a lock. t 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. t Dv LK_EXCLOTHER return for .Fn lockstatus . Used when another thread holds the lock exclusively. .El .Sh RETURN VALUES Successfully obtained locks return 0. Locks will always succeed unless one of the following is true: .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 . .Dv LK_SLEEPFAIL is set and a sleep was done; returns .Er ENOLCK . .Dv PCATCH is set in lock priority and a signal arrives; returns either .Er EINTR or .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).