--- name: "lockmgr" section: "9freebsd" platform: "linux" package: "freebsd-manpages" version: "12.2-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/lock/9freebsd" --- # lockmgr(9freebsd) lockmgr family of functions Part of [lock(9freebsd)](/lock/9freebsd.md). ## NAME **lockinit**, **lockdestroy**, **lockmgr**, **lockmgr\_args**, **lockmgr\_args\_rw**, **lockmgr\_disown**, **lockmgr\_printinfo**, **lockmgr\_recursed**, **lockmgr\_rw**, **lockstatus**, **lockmgr\_assert** – lockmgr family of functions ## SYNOPSIS **#include \** **#include \** **#include \** *void*\ **lockinit**(*struct lock \*lkp*, *int prio*, *const char \*wmesg*, *int timo*, *int flags*); *void*\ **lockdestroy**(*struct lock \*lkp*); *int*\ **lockmgr**(*struct lock \*lkp*, *u\_int flags*, *struct mtx \*ilk*); *int*\ **lockmgr\_args**(*struct lock \*lkp*, *u\_int flags*, *struct mtx \*ilk*, *const char \*wmesg*, *int prio*, *int timo*); *int*\ **lockmgr\_args\_rw**(*struct lock \*lkp*, *u\_int flags*, *struct rwlock \*ilk*, *const char \*wmesg*, *int prio*, *int timo*); *void*\ **lockmgr\_disown**(*struct lock \*lkp*); *void*\ **lockmgr\_printinfo**(*const struct lock \*lkp*); *int*\ **lockmgr\_recursed**(*const struct lock \*lkp*); *int*\ **lockmgr\_rw**(*struct lock \*lkp*, *u\_int flags*, *struct rwlock \*ilk*); *int*\ **lockstatus**(*const struct lock \*lkp*); **options INVARIANTS** **options INVARIANT\_SUPPORT** *void*\ **lockmgr\_assert**(*const struct lock \*lkp*, *int what*); ## DESCRIPTION The **lockinit**() function is used to initialize a lock. It must be called before any operation can be performed on a lock. Its arguments are: - *lkp* A pointer to the lock to initialize. - *prio* The priority passed to [sleep(9)](/sleep/9.md). - *wmesg* The lock message. This is used for both debugging output and [sleep(9)](/sleep/9.md). - *timo* The timeout value passed to [sleep(9)](/sleep/9.md). - *flags* The flags the lock is to be initialized with: - LK\_CANRECURSE Allow recursive exclusive locks. - LK\_NOPROFILE Disable lock profiling for this lock. - LK\_NOSHARE Allow exclusive locks only. - LK\_NOWITNESS Instruct [witness(4)](/witness/4.md) to ignore this lock. - LK\_NODUP [witness(4)](/witness/4.md) should log messages about duplicate locks being acquired. - LK\_QUIET Disable [ktr(4)](/ktr/4.md) logging for this lock. - LK\_TIMELOCK Use *timo* during a sleep; otherwise, 0 is used. The **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. The **lockmgr**() and **lockmgr\_rw**() functions handle general locking functionality within the kernel, including support for shared and exclusive locks, and recursion. **lockmgr**() and **lockmgr\_rw**() are also able to upgrade and downgrade locks. Their arguments are: - *lkp* A pointer to the lock to manipulate. - *flags* Flags indicating what action is to be taken. - LK\_SHARED Acquire a shared lock. If an exclusive lock is currently held, EDEADLK will be returned. - LK\_EXCLUSIVE Acquire an exclusive lock. If an exclusive lock is already held, and LK\_CANRECURSE is not set, the system will [panic(9)](/panic/9.md). - LK\_DOWNGRADE Downgrade exclusive lock to a shared lock. Downgrading a shared lock is not permitted. If an exclusive lock has been recursed, the system will [panic(9)](/panic/9.md). - LK\_UPGRADE Upgrade a shared lock to an exclusive lock. If this call fails, the shared lock is lost, even if the LK\_NOWAIT flag is specified. During the upgrade, the shared lock could be temporarily dropped. Attempts to upgrade an exclusive lock will cause a [panic(9)](/panic/9.md). - LK\_TRYUPGRADE Try to upgrade a shared lock to an exclusive lock. The failure to upgrade does not result in the dropping of the shared lock ownership. - LK\_RELEASE Release the lock. Releasing a lock that is not held can cause a [panic(9)](/panic/9.md). - LK\_DRAIN 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 ⟨sys/lockmgr.h⟩.) - LK\_SLEEPFAIL Fail if operation has slept. - LK\_NOWAIT Do not allow the call to sleep. This can be used to test the lock. - LK\_NOWITNESS Skip the [witness(4)](/witness/4.md) checks for this instance. - LK\_CANRECURSE Allow recursion on an exclusive lock. For every lock there must be a release. - LK\_INTERLOCK Unlock the interlock (which should be locked already). - LK\_NODDLKTREAT Normally, **lockmgr**() postpones serving further shared requests for shared-locked lock if there is exclusive waiter, to avoid exclusive lock starvation. But, if the thread requesting the shared lock already owns a shared lockmgr lock, the request is granted even in presence of the parallel exclusive lock request, which is done to avoid deadlocks with recursive shared acquisition. The LK\_NODDLKTREAT flag can only be used by code which requests shared non-recursive lock. The flag allows exclusive requests to preempt the current shared request even if the current thread owns shared locks. This is safe since shared lock is guaranteed to not recurse, and is used when thread is known to held unrelated shared locks, to not cause unnecessary starvation. An example is vp locking in VFS lookup(9), when dvp is already locked. - *ilk* An interlock mutex for controlling group access to the lock. If LK\_INTERLOCK is specified, **lockmgr**() and **lockmgr\_rw**() assume *ilk* is currently owned and not recursed, and will return it unlocked. See [mtx\_assert(9)](/mtx_assert/9.md). The **lockmgr\_args**() and **lockmgr\_args\_rw**() function work like **lockmgr**() and **lockmgr\_rw**() but accepting a *wmesg*, *timo* and *prio* on a per-instance basis. The specified values will override the default ones, but this can still be used passing, respectively, LK\_WMESG\_DEFAULT, LK\_PRIO\_DEFAULT and LK\_TIMO\_DEFAULT. The **lockmgr\_disown**() function switches the owner from the current thread to be LK\_KERNPROC, if the lock is already held. The **lockmgr\_printinfo**() function prints debugging information about the lock. It is used primarily by [VOP\_PRINT(9)](/VOP_PRINT/9.md) functions. The **lockmgr\_recursed**() function returns true if the lock is recursed, 0 otherwise. The **lockstatus**() function returns the status of the lock in relation to the current thread. When compiled with **options INVARIANTS** and **options INVARIANT\_SUPPORT**, the **lockmgr\_assert**() function tests *lkp* for the assertions specified in *what*, and panics if they are not met. One of the following assertions must be specified: - KA\_LOCKED Assert that the current thread has either a shared or an exclusive lock on the *lkp* lock pointed to by the first argument. - KA\_SLOCKED Assert that the current thread has a shared lock on the *lkp* lock pointed to by the first argument. - KA\_XLOCKED Assert that the current thread has an exclusive lock on the *lkp* lock pointed to by the first argument. - KA\_UNLOCKED Assert that the current thread has no lock on the *lkp* lock pointed to by the first argument. In addition, one of the following optional assertions can be used with either an KA\_LOCKED, KA\_SLOCKED, or KA\_XLOCKED assertion: - KA\_RECURSED Assert that the current thread has a recursed lock on *lkp*. - KA\_NOTRECURSED Assert that the current thread does not have a recursed lock on *lkp*. ## RETURN VALUES The **lockmgr**() and **lockmgr\_rw**() functions return 0 on success and non-zero on failure. The **lockstatus**() function returns: - LK\_EXCLUSIVE An exclusive lock is held by the current thread. - LK\_EXCLOTHER An exclusive lock is held by someone other than the current thread. - LK\_SHARED A shared lock is held. - 0 The lock is not held by anyone. ## ERRORS **lockmgr**() and **lockmgr\_rw**() fail if: - \[EBUSY\] LK\_FORCEUPGRADE was requested and another thread had already requested a lock upgrade. - \[EBUSY\] LK\_NOWAIT was set, and a sleep would have been required, or LK\_TRYUPGRADE operation was not able to upgrade the lock. - \[ENOLCK\] LK\_SLEEPFAIL was set and **lockmgr**() or **lockmgr\_rw**() did sleep. - \[EINTR\] PCATCH was set in the lock priority, and a signal was delivered during a sleep. Note the ERESTART error below. - \[ERESTART\] PCATCH was set in the lock priority, a signal was delivered during a sleep, and the system call is to be restarted. - \[EWOULDBLOCK\] a non-zero timeout was given, and the timeout expired. ## LOCKS If LK\_INTERLOCK is passed in the *flags* argument to **lockmgr**() or **lockmgr\_rw**(), the *ilk* must be held prior to calling **lockmgr**() or **lockmgr\_rw**(), and will be returned unlocked. 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 [panic(9)](/panic/9.md) will be the result of trying. ## SEE ALSO [condvar(9)](/condvar/9.md), [locking(9)](/locking/9.md), [mtx\_assert(9)](/mtx_assert/9.md), [mutex(9)](/mutex/9.md), [panic(9)](/panic/9.md), [rwlock(9)](/rwlock/9.md), [sleep(9)](/sleep/9.md), [sx(9)](/sx/9.md), [VOP\_PRINT(9)](/VOP_PRINT/9.md) ## AUTHORS This manual page was written by Chad David ⟨*davidc@acns.ab.ca*⟩.