[lkml]   [2020]   [Mar]   [14]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
Patch in this message
Subject[PATCH] docs: deprecated.rst: Add BUG()-family
Linus continues to remind[1] people to stop using the BUG()-family of
functions. We should have this better documented (even if
has been warning[2] since 2015), so add more details to deprecated.rst,
as a distinct place to point people to for guidance.


Signed-off-by: Kees Cook <>
Documentation/process/deprecated.rst | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)

diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index 8965446f0b71..38843c7a9ad6 100644
--- a/Documentation/process/deprecated.rst
+++ b/Documentation/process/deprecated.rst
@@ -29,6 +29,28 @@ a header file, it isn't the full solution. Such interfaces must either
be fully removed from the kernel, or added to this file to discourage
others from using them in the future.

+BUG() and BUG_ON()
+Use WARN() and WARN_ON() instead, and handle the "impossible"
+error condition as gracefully as possible. While the BUG()-family
+of APIs were originally designed to act as an "impossible situation"
+assert and to kill a kernel thread "safely", they turn out to just be
+too risky. (e.g. "In what order do locks need to be released? Have
+various states been restored?") Very commonly, using BUG() will
+destabilize a system or entirely break it, which makes it impossible
+to debug or even get viable crash reports. Linus has `very strong
+feelings `about this
+Note that the WARN()-family should only be used for "expected to
+be unreachable" situations. If you want to warn about "reachable
+but undesirable" situations, please use the pr_warn()-family of
+functions. System owners may have set the *panic_on_warn* sysctl,
+to make sure their systems do not continue running in the face of
+"unreachable" conditions. (For example, see commits like `this one
open-coded arithmetic in allocator arguments
Dynamic size calculations (especially multiplication) should not be

Kees Cook

 \ /
  Last update: 2020-03-15 03:30    [W:0.049 / U:3.792 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site