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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.