Documentation/core-api/printk-basics.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===========================
   4 Message logging with printk
   5 ===========================
   6
   7 printk() is one of the most widely known functions in the Linux kernel. It's the
   8 standard tool we have for printing messages and usually the most basic way of
   9 tracing and debugging. If you're familiar with printf(3) you can tell printk()
  10 is based on it, although it has some functional differences:
  11
  12   - printk() messages can specify a log level.
  13
  14   - the format string, while largely compatible with C99, doesn't follow the
  15     exact same specification. It has some extensions and a few limitations
  16     (no ``%n`` or floating point conversion specifiers). See :ref:`How to get
  17     printk format specifiers right <printk-specifiers>`.
  18
  19 All printk() messages are printed to the kernel log buffer, which is a ring
  20 buffer exported to userspace through /dev/kmsg. The usual way to read it is
  21 using ``dmesg``.
  22
  23 printk() is typically used like this::
  24
  25   printk(KERN_INFO "Message: %s\n", arg);
  26
  27 where ``KERN_INFO`` is the log level (note that it's concatenated to the format
  28 string, the log level is not a separate argument). The available log levels are:
  29
  30 +----------------+--------+-----------------------------------------------+
  31 | Name           | String |  Alias function                               |
  32 +================+========+===============================================+
  33 | KERN_EMERG     | "0"    | pr_emerg()                                    |
  34 +----------------+--------+-----------------------------------------------+
  35 | KERN_ALERT     | "1"    | pr_alert()                                    |
  36 +----------------+--------+-----------------------------------------------+
  37 | KERN_CRIT      | "2"    | pr_crit()                                     |
  38 +----------------+--------+-----------------------------------------------+
  39 | KERN_ERR       | "3"    | pr_err()                                      |
  40 +----------------+--------+-----------------------------------------------+
  41 | KERN_WARNING   | "4"    | pr_warn()                                     |
  42 +----------------+--------+-----------------------------------------------+
  43 | KERN_NOTICE    | "5"    | pr_notice()                                   |
  44 +----------------+--------+-----------------------------------------------+
  45 | KERN_INFO      | "6"    | pr_info()                                     |
  46 +----------------+--------+-----------------------------------------------+
  47 | KERN_DEBUG     | "7"    | pr_debug() and pr_devel() if DEBUG is defined |
  48 +----------------+--------+-----------------------------------------------+
  49 | KERN_DEFAULT   | ""     |                                               |
  50 +----------------+--------+-----------------------------------------------+
  51 | KERN_CONT      | "c"    | pr_cont()                                     |
  52 +----------------+--------+-----------------------------------------------+
  53
  54
  55 The log level specifies the importance of a message. The kernel decides whether
  56 to show the message immediately (printing it to the current console) depending
  57 on its log level and the current *console_loglevel* (a kernel variable). If the
  58 message priority is higher (lower log level value) than the *console_loglevel*
  59 the message will be printed to the console.
  60
  61 If the log level is omitted, the message is printed with ``KERN_DEFAULT``
  62 level.
  63
  64 You can check the current *console_loglevel* with::
  65
  66   $ cat /proc/sys/kernel/printk
  67   4        4        1        7
  68
  69 The result shows the *current*, *default*, *minimum* and *boot-time-default* log
  70 levels.
  71
  72 To change the current console_loglevel simply write the desired level to
  73 ``/proc/sys/kernel/printk``. For example, to print all messages to the console::
  74
  75   # echo 8 > /proc/sys/kernel/printk
  76
  77 Another way, using ``dmesg``::
  78
  79   # dmesg -n 5
  80
  81 sets the console_loglevel to print KERN_WARNING (4) or more severe messages to
  82 console. See ``dmesg(1)`` for more information.
  83
  84 As an alternative to printk() you can use the ``pr_*()`` aliases for
  85 logging. This family of macros embed the log level in the macro names. For
  86 example::
  87
  88   pr_info("Info message no. %d\n", msg_num);
  89
  90 prints a ``KERN_INFO`` message.
  91
  92 Besides being more concise than the equivalent printk() calls, they can use a
  93 common definition for the format string through the pr_fmt() macro. For
  94 instance, defining this at the top of a source file (before any ``#include``
  95 directive)::
  96
  97   #define pr_fmt(fmt) "%s:%s: " fmt, KBUILD_MODNAME, __func__
  98
  99 would prefix every pr_*() message in that file with the module and function name
 100 that originated the message.
 101
 102 For debugging purposes there are also two conditionally-compiled macros:
 103 pr_debug() and pr_devel(), which are compiled-out unless ``DEBUG`` (or
 104 also ``CONFIG_DYNAMIC_DEBUG`` in the case of pr_debug()) is defined.
 105
 106
 107 Function reference
 108 ==================
 109
 110 .. kernel-doc:: kernel/printk/printk.c
 111    :functions: printk
 112
 113 .. kernel-doc:: include/linux/printk.h
 114    :functions: pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info
 115       pr_fmt pr_debug pr_devel pr_cont