0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===========================
0004 Message logging with printk
0005 ===========================
0006
0007 printk() is one of the most widely known functions in the Linux kernel. It's the
0008 standard tool we have for printing messages and usually the most basic way of
0009 tracing and debugging. If you're familiar with printf(3) you can tell printk()
0010 is based on it, although it has some functional differences:
0011
0012 - printk() messages can specify a log level.
0013
0014 - the format string, while largely compatible with C99, doesn't follow the
0015 exact same specification. It has some extensions and a few limitations
0016 (no ``%n`` or floating point conversion specifiers). See :ref:`How to get
0017 printk format specifiers right <printk-specifiers>`.
0018
0019 All printk() messages are printed to the kernel log buffer, which is a ring
0020 buffer exported to userspace through /dev/kmsg. The usual way to read it is
0021 using ``dmesg``.
0022
0023 printk() is typically used like this::
0024
0025 printk(KERN_INFO "Message: %s\n", arg);
0026
0027 where ``KERN_INFO`` is the log level (note that it's concatenated to the format
0028 string, the log level is not a separate argument). The available log levels are:
0029
0030 +----------------+--------+-----------------------------------------------+
0031 | Name | String | Alias function |
0032 +================+========+===============================================+
0033 | KERN_EMERG | "0" | pr_emerg() |
0034 +----------------+--------+-----------------------------------------------+
0035 | KERN_ALERT | "1" | pr_alert() |
0036 +----------------+--------+-----------------------------------------------+
0037 | KERN_CRIT | "2" | pr_crit() |
0038 +----------------+--------+-----------------------------------------------+
0039 | KERN_ERR | "3" | pr_err() |
0040 +----------------+--------+-----------------------------------------------+
0041 | KERN_WARNING | "4" | pr_warn() |
0042 +----------------+--------+-----------------------------------------------+
0043 | KERN_NOTICE | "5" | pr_notice() |
0044 +----------------+--------+-----------------------------------------------+
0045 | KERN_INFO | "6" | pr_info() |
0046 +----------------+--------+-----------------------------------------------+
0047 | KERN_DEBUG | "7" | pr_debug() and pr_devel() if DEBUG is defined |
0048 +----------------+--------+-----------------------------------------------+
0049 | KERN_DEFAULT | "" | |
0050 +----------------+--------+-----------------------------------------------+
0051 | KERN_CONT | "c" | pr_cont() |
0052 +----------------+--------+-----------------------------------------------+
0053
0054
0055 The log level specifies the importance of a message. The kernel decides whether
0056 to show the message immediately (printing it to the current console) depending
0057 on its log level and the current *console_loglevel* (a kernel variable). If the
0058 message priority is higher (lower log level value) than the *console_loglevel*
0059 the message will be printed to the console.
0060
0061 If the log level is omitted, the message is printed with ``KERN_DEFAULT``
0062 level.
0063
0064 You can check the current *console_loglevel* with::
0065
0066 $ cat /proc/sys/kernel/printk
0067 4 4 1 7
0068
0069 The result shows the *current*, *default*, *minimum* and *boot-time-default* log
0070 levels.
0071
0072 To change the current console_loglevel simply write the desired level to
0073 ``/proc/sys/kernel/printk``. For example, to print all messages to the console::
0074
0075 # echo 8 > /proc/sys/kernel/printk
0076
0077 Another way, using ``dmesg``::
0078
0079 # dmesg -n 5
0080
0081 sets the console_loglevel to print KERN_WARNING (4) or more severe messages to
0082 console. See ``dmesg(1)`` for more information.
0083
0084 As an alternative to printk() you can use the ``pr_*()`` aliases for
0085 logging. This family of macros embed the log level in the macro names. For
0086 example::
0087
0088 pr_info("Info message no. %d\n", msg_num);
0089
0090 prints a ``KERN_INFO`` message.
0091
0092 Besides being more concise than the equivalent printk() calls, they can use a
0093 common definition for the format string through the pr_fmt() macro. For
0094 instance, defining this at the top of a source file (before any ``#include``
0095 directive)::
0096
0097 #define pr_fmt(fmt) "%s:%s: " fmt, KBUILD_MODNAME, __func__
0098
0099 would prefix every pr_*() message in that file with the module and function name
0100 that originated the message.
0101
0102 For debugging purposes there are also two conditionally-compiled macros:
0103 pr_debug() and pr_devel(), which are compiled-out unless ``DEBUG`` (or
0104 also ``CONFIG_DYNAMIC_DEBUG`` in the case of pr_debug()) is defined.
0105
0106
0107 Function reference
0108 ==================
0109
0110 .. kernel-doc:: include/linux/printk.h
0111 :functions: printk pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info
0112 pr_fmt pr_debug pr_devel pr_cont
