printk-basics.rst 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115
  1. .. SPDX-License-Identifier: GPL-2.0
  2. ===========================
  3. Message logging with printk
  4. ===========================
  5. printk() is one of the most widely known functions in the Linux kernel. It's the
  6. standard tool we have for printing messages and usually the most basic way of
  7. tracing and debugging. If you're familiar with printf(3) you can tell printk()
  8. is based on it, although it has some functional differences:
  9. - printk() messages can specify a log level.
  10. - the format string, while largely compatible with C99, doesn't follow the
  11. exact same specification. It has some extensions and a few limitations
  12. (no ``%n`` or floating point conversion specifiers). See :ref:`How to get
  13. printk format specifiers right <printk-specifiers>`.
  14. All printk() messages are printed to the kernel log buffer, which is a ring
  15. buffer exported to userspace through /dev/kmsg. The usual way to read it is
  16. using ``dmesg``.
  17. printk() is typically used like this::
  18. printk(KERN_INFO "Message: %s\n", arg);
  19. where ``KERN_INFO`` is the log level (note that it's concatenated to the format
  20. string, the log level is not a separate argument). The available log levels are:
  21. +----------------+--------+-----------------------------------------------+
  22. | Name | String | Alias function |
  23. +================+========+===============================================+
  24. | KERN_EMERG | "0" | pr_emerg() |
  25. +----------------+--------+-----------------------------------------------+
  26. | KERN_ALERT | "1" | pr_alert() |
  27. +----------------+--------+-----------------------------------------------+
  28. | KERN_CRIT | "2" | pr_crit() |
  29. +----------------+--------+-----------------------------------------------+
  30. | KERN_ERR | "3" | pr_err() |
  31. +----------------+--------+-----------------------------------------------+
  32. | KERN_WARNING | "4" | pr_warn() |
  33. +----------------+--------+-----------------------------------------------+
  34. | KERN_NOTICE | "5" | pr_notice() |
  35. +----------------+--------+-----------------------------------------------+
  36. | KERN_INFO | "6" | pr_info() |
  37. +----------------+--------+-----------------------------------------------+
  38. | KERN_DEBUG | "7" | pr_debug() and pr_devel() if DEBUG is defined |
  39. +----------------+--------+-----------------------------------------------+
  40. | KERN_DEFAULT | "" | |
  41. +----------------+--------+-----------------------------------------------+
  42. | KERN_CONT | "c" | pr_cont() |
  43. +----------------+--------+-----------------------------------------------+
  44. The log level specifies the importance of a message. The kernel decides whether
  45. to show the message immediately (printing it to the current console) depending
  46. on its log level and the current *console_loglevel* (a kernel variable). If the
  47. message priority is higher (lower log level value) than the *console_loglevel*
  48. the message will be printed to the console.
  49. If the log level is omitted, the message is printed with ``KERN_DEFAULT``
  50. level.
  51. You can check the current *console_loglevel* with::
  52. $ cat /proc/sys/kernel/printk
  53. 4 4 1 7
  54. The result shows the *current*, *default*, *minimum* and *boot-time-default* log
  55. levels.
  56. To change the current console_loglevel simply write the desired level to
  57. ``/proc/sys/kernel/printk``. For example, to print all messages to the console::
  58. # echo 8 > /proc/sys/kernel/printk
  59. Another way, using ``dmesg``::
  60. # dmesg -n 5
  61. sets the console_loglevel to print KERN_WARNING (4) or more severe messages to
  62. console. See ``dmesg(1)`` for more information.
  63. As an alternative to printk() you can use the ``pr_*()`` aliases for
  64. logging. This family of macros embed the log level in the macro names. For
  65. example::
  66. pr_info("Info message no. %d\n", msg_num);
  67. prints a ``KERN_INFO`` message.
  68. Besides being more concise than the equivalent printk() calls, they can use a
  69. common definition for the format string through the pr_fmt() macro. For
  70. instance, defining this at the top of a source file (before any ``#include``
  71. directive)::
  72. #define pr_fmt(fmt) "%s:%s: " fmt, KBUILD_MODNAME, __func__
  73. would prefix every pr_*() message in that file with the module and function name
  74. that originated the message.
  75. For debugging purposes there are also two conditionally-compiled macros:
  76. pr_debug() and pr_devel(), which are compiled-out unless ``DEBUG`` (or
  77. also ``CONFIG_DYNAMIC_DEBUG`` in the case of pr_debug()) is defined.
  78. Function reference
  79. ==================
  80. .. kernel-doc:: kernel/printk/printk.c
  81. :functions: printk
  82. .. kernel-doc:: include/linux/printk.h
  83. :functions: pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info
  84. pr_fmt pr_debug pr_devel pr_cont