xref: /linux/Documentation/core-api/printk-basics.rst (revision b8265621f4888af9494e1d685620871ec81bc33d) 
1.. SPDX-License-Identifier: GPL-2.0
2
3===========================
4Message logging with printk
5===========================
6
7printk() is one of the most widely known functions in the Linux kernel. It's the
8standard tool we have for printing messages and usually the most basic way of
9tracing and debugging. If you're familiar with printf(3) you can tell printk()
10is 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
19All printk() messages are printed to the kernel log buffer, which is a ring
20buffer exported to userspace through /dev/kmsg. The usual way to read it is
21using ``dmesg``.
22
23printk() is typically used like this::
24
25  printk(KERN_INFO "Message: %s\n", arg);
26
27where ``KERN_INFO`` is the log level (note that it's concatenated to the format
28string, 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
55The log level specifies the importance of a message. The kernel decides whether
56to show the message immediately (printing it to the current console) depending
57on its log level and the current *console_loglevel* (a kernel variable). If the
58message priority is higher (lower log level value) than the *console_loglevel*
59the message will be printed to the console.
60
61If the log level is omitted, the message is printed with ``KERN_DEFAULT``
62level.
63
64You can check the current *console_loglevel* with::
65
66  $ cat /proc/sys/kernel/printk
67  4        4        1        7
68
69The result shows the *current*, *default*, *minimum* and *boot-time-default* log
70levels.
71
72To change the current console_loglevel simply write the 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
77Another way, using ``dmesg``::
78
79  # dmesg -n 5
80
81sets the console_loglevel to print KERN_WARNING (4) or more severe messages to
82console. See ``dmesg(1)`` for more information.
83
84As an alternative to printk() you can use the ``pr_*()`` aliases for
85logging. This family of macros embed the log level in the macro names. For
86example::
87
88  pr_info("Info message no. %d\n", msg_num);
89
90prints a ``KERN_INFO`` message.
91
92Besides being more concise than the equivalent printk() calls, they can use a
93common definition for the format string through the pr_fmt() macro. For
94instance, defining this at the top of a source file (before any ``#include``
95directive)::
96
97  #define pr_fmt(fmt) "%s:%s: " fmt, KBUILD_MODNAME, __func__
98
99would prefix every pr_*() message in that file with the module and function name
100that originated the message.
101
102For debugging purposes there are also two conditionally-compiled macros:
103pr_debug() and pr_devel(), which are compiled-out unless ``DEBUG`` (or
104also ``CONFIG_DYNAMIC_DEBUG`` in the case of pr_debug()) is defined.
105
106
107Function 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
116