1.\" $OpenBSD: witness.4,v 1.5 2019/01/29 14:07:15 visa Exp $ 2.\" 3.\" Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD: head/share/man/man4/witness.4 301719 2016-06-09 06:55:00Z trasz $ 28.\" 29.Dd $Mdocdate: January 29 2019 $ 30.Dt WITNESS 4 31.Os 32.Sh NAME 33.Nm witness 34.Nd lock validation facility 35.Sh DESCRIPTION 36The 37.Nm 38module keeps track of the locks acquired and released by each thread. 39It also keeps track of the order in which locks are acquired with respect 40to each other. 41Each time a lock is acquired, 42.Nm 43uses these two lists to verify that a lock is not being acquired in the 44wrong order. 45If a lock order violation is detected, then a message is printed to the 46kernel console detailing the locks involved and the locations in question. 47.Pp 48The 49.Nm 50code also checks various other conditions such as verifying that one 51does not recurse on a non-recursive lock, 52or attempt an upgrade on a shared lock held by another thread. 53If any of these checks fail, then the kernel will panic. 54.Pp 55The behaviour of 56.Nm 57is controlled by the 58.Va kern.witness.watch 59.Xr sysctl 8 60variable. 61Valid values for it are: 62.Pp 63.Bl -tag -width 1nr -compact -offset indent 64.It \-1 65disable 66.Nm witness 67completely 68.It 0 69disable error checking 70.It 1 71print a message if an error is detected 72.It 2 73print a message and a stack trace if possible 74.It 3 75like 2 but also drop into the kernel debugger 76.El 77.Sh SEE ALSO 78.Xr ddb 4 , 79.Xr options 4 , 80.Xr sysctl 8 , 81.Xr mutex 9 , 82.Xr rwlock 9 83.Sh HISTORY 84The 85.Nm 86code first appeared in 87.Bsx 5.0 88and was imported from there into 89.Fx 5.0 . 90The 91.Ox 92port was derived from 93.Fx 94and first appeared in 95.Ox 6.2 . 96