Page MenuHomeFreeBSD
Files F157778573

D39131.id118953.diff
No OneTemporary
Actions

D39131.id118953.diff
View Options

diff --git a/share/man/man9/KASSERT.9 b/share/man/man9/KASSERT.9
--- a/share/man/man9/KASSERT.9
+++ b/share/man/man9/KASSERT.9
@@ -1,8 +1,11 @@
-.\" -*- nroff -*-
+.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2000 Jonathan M. Bresler
-.\"
.\" All rights reserved.
+.\" Copyright (c) 2023 The FreeBSD Foundation
+.\"
+.\" Portions of this documentation were written by Mitchell Horne
+.\" under sponsorship from the FreeBSD Foundation.
.\"
.\" This program is free software.
.\"
@@ -28,59 +31,95 @@
.\"
.\" $FreeBSD$
.\"
-.Dd January 14, 2000
+.Dd February 16, 2023
.Dt KASSERT 9
.Os
.Sh NAME
.Nm KASSERT
-.Nd kernel expression verification macro
+.Nd kernel expression verification macros
.Sh SYNOPSIS
.Cd "options INVARIANTS"
.Pp
.In sys/param.h
-.In sys/systm.h
+.In sys/kassert.h
.Fn KASSERT expression msg
+.Fn MPASS expression
.Sh DESCRIPTION
-In a kernel compiled with
-.Cd "options INVARIANTS" ,
-the
+Assertions are widely used within the
+.Fx
+kernel to verify programmatic assumptions.
+For violations of run-time assumptions, invariants, and other non-recoverable
+errors, it is desirable to fail as soon and as loudly as possible.
+.Pp
+The
.Fn KASSERT
-macro tests the given
+macro tests the given boolean
+.Fa expression .
+If
.Fa expression
-and if it is false,
-calls the
-.Xr panic 9
-function, terminating the running system.
-.Pp
-In a kernel that does not have
+evaluates to
+.Dv false ,
+and the kernel is compiled with
.Cd "options INVARIANTS" ,
the
-.Fn KASSERT
-macro is defined to be a no-op.
-The
-second argument is a
+.Xr panic 9
+function is called.
+This terminates the running system at the point of the error, possibly dropping
+into the kernel debugger or initiating a kernel core dump.
+The second argument,
+.Fa msg ,
+is a
.Xr printf 9
format string and its arguments,
enclosed in parentheses.
+.Fa msg
+will become the panic string.
+.Pp
+In a kernel that is built without
+.Cd "options INVARIANTS" ,
+the assertion macros are defined to be no-ops.
+This eliminates the runtime overhead of widespread assertions from release
+builds of the kernel.
+Therefore, programmers should not avoid the use of assertions for performance
+concerns, except in extreme cases.
+.Pp
+The
+.Fn MPASS
+macro (read as: "must-pass")
+is a convenience wrapper around
+.Fn KASSERT
+that generates a sensible assertion message including file and line
+information.
.Sh EXAMPLES
-The kernel function
-.Fn vput
+The function
+.Fn foo
must not be called with a
.Dv NULL
pointer.
.Bd -literal -offset indent
void
-vput(vp)
- struct vnode *vp;
+foo(struct bar *bp)
{
- struct proc *p = curproc;
- KASSERT(vp != NULL, ("vput: null vp"));
+
+ KASSERT(bp != NULL, ("foo: null bp"));
...
}
.Ed
+.Pp
+The assertion
+.Bd -literal -offset indent
+MPASS(td == curthread);
+.Ed
+.Pp
+located on line 87 of a file named foo.c would generate the following panic
+message:
+.Bd -literal -offset indent
+panic: Assertion td == cuthread failed at foo.c:87
+.Ed
.Sh SEE ALSO
-.Xr config 8 ,
.Xr panic 9
.Sh AUTHORS
This manual page was written by
-.An Jonathan M. Bresler Aq Mt jmb@FreeBSD.org .
+.An Jonathan M. Bresler Aq Mt jmb@FreeBSD.org
+and
+.An Mitchell Horne Aq Mt mhorne@FreeBSD.org .
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1333,6 +1333,7 @@
intr_event.9 intr_event_handle.9 \
intr_event.9 intr_event_remove_handler.9 \
intr_event.9 intr_priority.9
+MLINKS+=KASSERT.9 MPASS.9
MLINKS+=kern_yield.9 maybe_yield.9 \
kern_yield.9 should_yield.9
MLINKS+=kernacc.9 useracc.9

File Metadata

Mime Type
text/plain
Expires
Tue, May 26, 2:01 AM (2 h, 25 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
33522333
Default Alt Text
D39131.id118953.diff (3 KB)

Event Timeline