KeBugCheckEx function (wdm.h)

Article
02/25/2022

The KeBugCheckEx routine brings down the system in a controlled manner when the caller discovers an unrecoverable inconsistency that would corrupt the system if the caller continued to run.

Syntax

void KeBugCheckEx(
  [in] ULONG     BugCheckCode,
  [in] ULONG_PTR BugCheckParameter1,
  [in] ULONG_PTR BugCheckParameter2,
  [in] ULONG_PTR BugCheckParameter3,
  [in] ULONG_PTR BugCheckParameter4
);

Parameters

[in] BugCheckCode

Specifies a value that indicates the reason for the bug check.

[in] BugCheckParameter1

[in] BugCheckParameter2

[in] BugCheckParameter3

[in] BugCheckParameter4

The four BugCheckParameterX values supply additional information, such as the address and data where a memory-corruption error occurred, depending on the value of BugCheckCode.

Return value

None

Remarks

A bug check is a system-detected error that causes an immediate, controlled shutdown of the system. Various kernel-mode components perform run-time consistency checking. When such a component discovers an unrecoverable inconsistency, it causes a bug check to be generated.

Whenever possible, all kernel-mode components should log an error and continue to run, rather than calling KeBugCheckEx. For example, if a driver is unable to allocate required resources, it should log an error so that the system continues to run; it must not generate a bug check.

A driver or other kernel-mode component should call this routine only in cases of a fatal, unrecoverable error that could corrupt the system itself.

KeBugCheckEx can be useful in the early stages of developing a driver, or while it is undergoing testing. In these circumstances, the BugCheckCode passed to this routine should be distinct from those codes already in use by Windows or its drivers. For a list of these codes, see Bug Check Codes.

However, even during driver development, this routine is of only limited utility, since it results in a complete system shutdown. A more effective debugging method is to attach a kernel debugger to the system and then use routines that send messages to the debugger or break into the debugger. For further information, see Using Debugging Code in a Driver.

Requirements


Minimum supported client	Available in Windows 2000 and later versions of Windows.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Any level