Commit | Line | Data |
---|---|---|
90c165f0 RC |
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 | ||
6566945f | 72 | To change the current console_loglevel simply write the desired level to |
90c165f0 RC |
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 | ||
90c165f0 | 110 | .. kernel-doc:: include/linux/printk.h |
7d9e2661 | 111 | :functions: printk pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info |
90c165f0 | 112 | pr_fmt pr_debug pr_devel pr_cont |