Kay Sievers | 3b552b9 | 2012-05-08 18:50:50 +0200 | [diff] [blame] | 1 | What: /dev/kmsg |
| 2 | Date: Mai 2012 |
| 3 | KernelVersion: 3.5 |
| 4 | Contact: Kay Sievers <kay@vrfy.org> |
| 5 | Description: The /dev/kmsg character device node provides userspace access |
| 6 | to the kernel's printk buffer. |
| 7 | |
| 8 | Injecting messages: |
| 9 | Every write() to the opened device node places a log entry in |
| 10 | the kernel's printk buffer. |
| 11 | |
| 12 | The logged line can be prefixed with a <N> syslog prefix, which |
| 13 | carries the syslog priority and facility. The single decimal |
| 14 | prefix number is composed of the 3 lowest bits being the syslog |
| 15 | priority and the higher bits the syslog facility number. |
| 16 | |
| 17 | If no prefix is given, the priority number is the default kernel |
| 18 | log priority and the facility number is set to LOG_USER (1). It |
| 19 | is not possible to inject messages from userspace with the |
| 20 | facility number LOG_KERN (0), to make sure that the origin of |
| 21 | the messages can always be reliably determined. |
| 22 | |
| 23 | Accessing the buffer: |
| 24 | Every read() from the opened device node receives one record |
| 25 | of the kernel's printk buffer. |
| 26 | |
| 27 | The first read() directly following an open() always returns |
| 28 | first message in the buffer; there is no kernel-internal |
| 29 | persistent state; many readers can concurrently open the device |
| 30 | and read from it, without affecting other readers. |
| 31 | |
| 32 | Every read() will receive the next available record. If no more |
| 33 | records are available read() will block, or if O_NONBLOCK is |
| 34 | used -EAGAIN returned. |
| 35 | |
| 36 | Messages in the record ring buffer get overwritten as whole, |
| 37 | there are never partial messages received by read(). |
| 38 | |
| 39 | In case messages get overwritten in the circular buffer while |
| 40 | the device is kept open, the next read() will return -EPIPE, |
| 41 | and the seek position be updated to the next available record. |
| 42 | Subsequent reads() will return available records again. |
| 43 | |
| 44 | Unlike the classic syslog() interface, the 64 bit record |
| 45 | sequence numbers allow to calculate the amount of lost |
| 46 | messages, in case the buffer gets overwritten. And they allow |
| 47 | to reconnect to the buffer and reconstruct the read position |
| 48 | if needed, without limiting the interface to a single reader. |
| 49 | |
| 50 | The device supports seek with the following parameters: |
| 51 | SEEK_SET, 0 |
| 52 | seek to the first entry in the buffer |
| 53 | SEEK_END, 0 |
| 54 | seek after the last entry in the buffer |
| 55 | SEEK_DATA, 0 |
| 56 | seek after the last record available at the time |
| 57 | the last SYSLOG_ACTION_CLEAR was issued. |
| 58 | |
| 59 | The output format consists of a prefix carrying the syslog |
| 60 | prefix including priority and facility, the 64 bit message |
Kay Sievers | d39f3d7 | 2012-07-16 18:35:30 -0700 | [diff] [blame] | 61 | sequence number and the monotonic timestamp in microseconds, |
| 62 | and a flag field. All fields are separated by a ','. |
| 63 | |
| 64 | Future extensions might add more comma separated values before |
| 65 | the terminating ';'. Unknown fields and values should be |
| 66 | gracefully ignored. |
Kay Sievers | 3b552b9 | 2012-05-08 18:50:50 +0200 | [diff] [blame] | 67 | |
| 68 | The human readable text string starts directly after the ';' |
| 69 | and is terminated by a '\n'. Untrusted values derived from |
| 70 | hardware or other facilities are printed, therefore |
Kay Sievers | d39f3d7 | 2012-07-16 18:35:30 -0700 | [diff] [blame] | 71 | all non-printable characters and '\' itself in the log message |
| 72 | are escaped by "\x00" C-style hex encoding. |
Kay Sievers | 3b552b9 | 2012-05-08 18:50:50 +0200 | [diff] [blame] | 73 | |
| 74 | A line starting with ' ', is a continuation line, adding |
| 75 | key/value pairs to the log message, which provide the machine |
| 76 | readable context of the message, for reliable processing in |
| 77 | userspace. |
| 78 | |
| 79 | Example: |
Kay Sievers | d39f3d7 | 2012-07-16 18:35:30 -0700 | [diff] [blame] | 80 | 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored) |
Kay Sievers | 3b552b9 | 2012-05-08 18:50:50 +0200 | [diff] [blame] | 81 | SUBSYSTEM=acpi |
| 82 | DEVICE=+acpi:PNP0A03:00 |
Kay Sievers | d39f3d7 | 2012-07-16 18:35:30 -0700 | [diff] [blame] | 83 | 6,339,5140900,-;NET: Registered protocol family 10 |
| 84 | 30,340,5690716,-;udevd[80]: starting version 181 |
Kay Sievers | 3b552b9 | 2012-05-08 18:50:50 +0200 | [diff] [blame] | 85 | |
| 86 | The DEVICE= key uniquely identifies devices the following way: |
| 87 | b12:8 - block dev_t |
| 88 | c127:3 - char dev_t |
| 89 | n8 - netdev ifindex |
| 90 | +sound:card0 - subsystem:devname |
| 91 | |
Kay Sievers | d39f3d7 | 2012-07-16 18:35:30 -0700 | [diff] [blame] | 92 | The flags field carries '-' by default. A 'c' indicates a |
| 93 | fragment of a line. All following fragments are flagged with |
| 94 | '+'. Note, that these hints about continuation lines are not |
Masanari Iida | 4e79162a | 2012-11-08 21:57:35 +0900 | [diff] [blame] | 95 | necessarily correct, and the stream could be interleaved with |
Kay Sievers | d39f3d7 | 2012-07-16 18:35:30 -0700 | [diff] [blame] | 96 | unrelated messages, but merging the lines in the output |
| 97 | usually produces better human readable results. A similar |
| 98 | logic is used internally when messages are printed to the |
| 99 | console, /proc/kmsg or the syslog() syscall. |
| 100 | |
Tejun Heo | 6fe2935 | 2015-06-25 15:01:30 -0700 | [diff] [blame] | 101 | By default, kernel tries to avoid fragments by concatenating |
| 102 | when it can and fragments are rare; however, when extended |
| 103 | console support is enabled, the in-kernel concatenation is |
| 104 | disabled and /dev/kmsg output will contain more fragments. If |
| 105 | the log consumer performs concatenation, the end result |
| 106 | should be the same. In the future, the in-kernel concatenation |
| 107 | may be removed entirely and /dev/kmsg users are recommended to |
| 108 | implement fragment handling. |
| 109 | |
Kay Sievers | 3b552b9 | 2012-05-08 18:50:50 +0200 | [diff] [blame] | 110 | Users: dmesg(1), userspace kernel log consumers |