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.\" $FreeBSD$ 33.\" 34.Dd March 16, 2023 35.Dt KASSERT 9 36.Os 37.Sh NAME 38.Nm KASSERT 39.Nd kernel expression verification macros 40.Sh SYNOPSIS 41.Cd "options INVARIANTS" 42.Pp 43.In sys/param.h 44.In sys/systm.h 45.Fn KASSERT expression msg 46.Fn MPASS expression 47.Sh DESCRIPTION 48Assertions are widely used within the 49.Fx 50kernel to verify programmatic assumptions. 51For violations of run-time assumptions and invariants, it is desirable to fail 52as soon and as loudly as possible. 53Assertions are optional code; for non-recoverable error conditions an explicit 54call to 55.Xr panic 9 56is usually preferred. 57.Pp 58The 59.Fn KASSERT 60macro tests the given boolean 61.Fa expression . 62If 63.Fa expression 64evaluates to 65.Dv false , 66and the kernel is compiled with 67.Cd "options INVARIANTS" , 68the 69.Xr panic 9 70function is called. 71This terminates the running system at the point of the error, possibly dropping 72into the kernel debugger or initiating a kernel core dump. 73The second argument, 74.Fa msg , 75is a 76.Xr printf 9 77format string and its arguments, 78enclosed in parentheses. 79The formatted string will become the panic string. 80.Pp 81In a kernel that is built without 82.Cd "options INVARIANTS" , 83the assertion macros are defined to be no-ops. 84This eliminates the runtime overhead of widespread assertions from release 85builds of the kernel. 86Therefore, checks which can be performed in a constant amount of time can be 87added as assertions without concern about their performance impact. 88More expensive checks, such as those that output to console, or verify the 89integrity of a chain of objects are generally best hidden behind the 90.Cd DIAGNOSTIC 91kernel option. 92.Pp 93The 94.Fn MPASS 95macro (read as: "must-pass") 96is a convenience wrapper around 97.Fn KASSERT 98that automatically generates a sensible assertion message including file and 99line information. 100.Sh EXAMPLES 101A hypothetical 102.Vt struct foo 103object must not have its 'active' flag set when calling 104.Fn foo_dealloc : 105.Bd -literal -offset indent 106void 107foo_dealloc(struct foo *fp) 108{ 109 110 KASSERT((fp->foo_flags & FOO_ACTIVE) == 0, 111 ("%s: fp %p is still active", __func__, fp)); 112 ... 113} 114.Ed 115.Pp 116The assertion 117.Bd -literal -offset indent 118MPASS(td == curthread); 119.Ed 120.Pp 121located on line 87 of a file named foo.c would generate the following panic 122message: 123.Bd -literal -offset indent 124panic: Assertion td == curthread failed at foo.c:87 125.Ed 126.Sh SEE ALSO 127.Xr panic 9 128.Sh AUTHORS 129This manual page was written by 130.An Jonathan M. Bresler Aq Mt jmb@FreeBSD.org 131and 132.An Mitchell Horne Aq Mt mhorne@FreeBSD.org . 133