GNU Linux-libre 6.6.34-gnu
[releases.git] / 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:: include/linux/printk.h
111    :functions: printk pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info
112       pr_fmt pr_debug pr_devel pr_cont