1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2000 Jonathan M. Bresler 4.\" All rights reserved. 5.\" Copyright (c) 2023 The FreeBSD Foundation 6.\" 7.\" Portions of this documentation were written by Mitchell Horne 8.\" under sponsorship from the FreeBSD Foundation. 9.\" 10.\" This program is free software. 11.\" 12.\" Redistribution and use in source and binary forms, with or without 13.\" modification, are permitted provided that the following conditions 14.\" are met: 15.\" 1. Redistributions of source code must retain the above copyright 16.\" notice, this list of conditions and the following disclaimer. 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in the 19.\" documentation and/or other materials provided with the distribution. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 24.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd March 16, 2023 33.Dt KASSERT 9 34.Os 35.Sh NAME 36.Nm KASSERT 37.Nd kernel expression verification macros 38.Sh SYNOPSIS 39.Cd "options INVARIANTS" 40.Pp 41.In sys/param.h 42.In sys/systm.h 43.Fn KASSERT expression msg 44.Fn MPASS expression 45.Sh DESCRIPTION 46Assertions are widely used within the 47.Fx 48kernel to verify programmatic assumptions. 49For violations of run-time assumptions and invariants, it is desirable to fail 50as soon and as loudly as possible. 51Assertions are optional code; for non-recoverable error conditions an explicit 52call to 53.Xr panic 9 54is usually preferred. 55.Pp 56The 57.Fn KASSERT 58macro tests the given boolean 59.Fa expression . 60If 61.Fa expression 62evaluates to 63.Dv false , 64and the kernel is compiled with 65.Cd "options INVARIANTS" , 66the 67.Xr panic 9 68function is called. 69This terminates the running system at the point of the error, possibly dropping 70into the kernel debugger or initiating a kernel core dump. 71The second argument, 72.Fa msg , 73is a 74.Xr printf 9 75format string and its arguments, 76enclosed in parentheses. 77The formatted string will become the panic string. 78.Pp 79In a kernel that is built without 80.Cd "options INVARIANTS" , 81the assertion macros are defined to be no-ops. 82This eliminates the runtime overhead of widespread assertions from release 83builds of the kernel. 84Therefore, checks which can be performed in a constant amount of time can be 85added as assertions without concern about their performance impact. 86More expensive checks, such as those that output to console, or verify the 87integrity of a chain of objects are generally best hidden behind the 88.Cd DIAGNOSTIC 89kernel option. 90.Pp 91The 92.Fn MPASS 93macro (read as: "must-pass") 94is a convenience wrapper around 95.Fn KASSERT 96that automatically generates a sensible assertion message including file and 97line information. 98.Sh EXAMPLES 99A hypothetical 100.Vt struct foo 101object must not have its 'active' flag set when calling 102.Fn foo_dealloc : 103.Bd -literal -offset indent 104void 105foo_dealloc(struct foo *fp) 106{ 107 108 KASSERT((fp->foo_flags & FOO_ACTIVE) == 0, 109 ("%s: fp %p is still active", __func__, fp)); 110 ... 111} 112.Ed 113.Pp 114The assertion 115.Bd -literal -offset indent 116MPASS(td == curthread); 117.Ed 118.Pp 119located on line 87 of a file named foo.c would generate the following panic 120message: 121.Bd -literal -offset indent 122panic: Assertion td == curthread failed at foo.c:87 123.Ed 124.Sh SEE ALSO 125.Xr panic 9 126.Sh AUTHORS 127This manual page was written by 128.An Jonathan M. Bresler Aq Mt jmb@FreeBSD.org 129and 130.An Mitchell Horne Aq Mt mhorne@FreeBSD.org . 131